Key-Value Container Literal

Summary

Creates a dictionary, map ("associative array"), or external JavaScript object and optionally populates it with key-value pairs.

Syntax

{
	key1: value1,
	key2: value2,
	key3: value3,
	...
	keyN: valueN
}

Parameters

keyN: A string key to associate with a value.
valueN: A value to associate with a corresponding key.

Description

The key-value container literal is a shorthand for creating dictionaries, ordered/unordered maps (or "associative arrays"), and external JavaScript objects. These containers hold key-value pairs and are represented by the System.Dictionary, System.OrderedMap, and System.UnorderedMap classes and the external type for external JavaScript objects.

Key-value container literals can be used as a shorthand in place of instantiating the System.Dictionary, System.OrderedMap, and System.UnorderedMap classes. For example, the following statements are equivalent:

Dictionary<int> numbers = {}; // Using key-value container literals
System.Dictionary<int> numbers = new System.Dictionary<int>(); // Using instantiation

The keys of the key-value container literal are always strings, and the values can be any user-defined type. All values in a dictionary must have a uniform type.

The interpretation order for key-value container literals ({ ... }) are: System.Dictionary, System.UnorderedMap, System.OrderedMap, external.

Accessing Container Elements

Each "element" of the container are key-value pairs. In other words, each value is associated with a "key" used to look up the value. Values can be looked up with the dictionary[key] syntax:

import System;
 
Dictionary<int> foo = {
    "bar": 10,
    "baz": 20,
    "qux": 30
};
 
Console.log(foo["bar"]); // 10
Console.log(foo["baz"]); // 20
Console.log(foo["qux"]); // 30

The JavaScript syntax for accessing object members using the dot operator, such as dictionary.key, is not used for looking up members of JS++ dictionaries. Instead, this will trigger a lookup for a member of the System.Dictionary class (such as a method) instead and cannot be used to access dynamic members of a container. This limitation is necessary for compile-time static analysis and consistency with other JS++ internal types.

Modifying Container Elements

The value associated with a key in a container can be modified using the dictionary[key] = ... syntax:

import System;
 
Dictionary<int> foo = {
    "bar": 10,
    "baz": 20,
    "qux": 30
};
 
Console.log(foo["bar"]); // 10
foo["bar"] = 100; // Modify the value of foo["bar"]
Console.log(foo["bar"]); // 100

Retrieving All Keys of the Container with 'for...in'

Each key of the container can be retrieved by looping the container with, for example, the for-in loop:

import System;
 
Dictionary<int> dict = {
    "bar": 10,
    "baz": 20,
    "qux": 30
};
 
for (string key in dict) {
    Console.log(key + " has value " + key[value]);
}
 
// Output:
// bar has value 10
// baz has value 20
// qux has value 30

Retrieving All Values of Container with 'foreach'

The values of the associative array can be retrieved by looping the associative array with, for example, the foreach loop:

import System;
 
Dictionary<int> dict = {
    "bar": 10,
    "baz": 20,
    "qux": 30
};
 
foreach (int value in dict) {
    Console.log(value);
}
 
// Output:
// 10
// 20
// 30

Differences with JavaScript Objects

If a key-value pair container or dictionary is desired, the recommendation is to avoid using JavaScript objects. In JS++, JavaScript objects have the external type. In other words, JavaScript objects cannot be guaranteed to be "type safe".

Additionally, JavaScript objects inherit from the entire prototype chain. Therefore, a for-in loop will look up the entire prototype chain for keys. This behavior may not be desirable and may create unexpected bugs. In contrast, the for...in and foreach loops for JS++ maps, dictionaries, and containers will only iterate the key-value pairs of the map/dictionary/container itself.

Examples

Looping Dictionaries (Associative Arrays)

import System;
 
Dictionary<unsigned int> employees = {
    "Peter": 39,
    "John": 24,
    "Joseph": 25
};
 
for (string name in employees) {
    unsigned int age = employees[name];
    Console.log(name + " is " + age + " years old.");
}
 
// Output:
// Peter is 39 years old.
// John is 24 years old.
// Joseph is 25 years old.