Dictionary<T>

Summary

System.Dictionary<T> is the wrapper class for dictionaries.

Description

The System.Dictionary<T> class is the wrapper class for dictionaries, a container for key-value pairs. System.Dictionary<T> is a specialization of System.UnorderedMap<K, V> with string-only keys.

Dictionaries are key-value pairs. The keys must be of the string (or System.String) type, but the values can be any uniform type (with sound covariance/contravariance). For arbitrary key types, use System.UnorderedMap<K, V>.

Dictionaries are not sorted in any particular order. For ordered key-value pairs, use System.OrderedMap<K, V>.

Accessing Keys/Values

Unlike JavaScript, JS++ dictionary keys cannot be accessed with the dot (.) operator. Instead, the index operator ([...]) must be used.

The primary reason for this is because - in order to guarantee the soundness of the JS++ type system - the dot (.) operator must reference only members of an object that can be resolved at compile time (such as class fields, methods, and properties). Meanwhile, the index operator ([...]) can be used to resolve keys, such as array indexes and dictionary keys, which can only be known at runtime.

Thus, it is acceptable to use the dot (.) operator to access the methods of System.Dictionary<T> like so:

1
2
3
4
import System;
 
Dictionary<int> dict = { a: 1, b: 2 };
Console.log(dict.contains("a")); // Calls the `System.Dictionary<int>.contains(string key)` method

However, trying to access dynamic keys are not acceptable usages for the dot (.) operator:

1
2
3
4
import System;
 
Dictionary<int> dict = { a: 1, b: 2 };
dict.a; // Compile-time error because 'a' is not a method or member defined for the class `System.Dictionary<int>`

In order to successfully compile the code above and access the "a" key, we must use the index ([...]) operator:

1
2
3
4
import System;
 
Dictionary<int> dict = { a: 1, b: 2 };
dict["a"]; // OK

Additionally, from a design perspective, dictionary keys being available only from the index ([...]) operator enables JS++ to provide a consistent syntax when the keys can be any arbitrary object rather than only strings (such as in the cases of System.OrderedMap<K, V> and System.UnorderedMap<K, V>).

Trying to access keys that are not in the dictionary will throw System.Exceptions.KeyUnavailableException.

Differences to JavaScript

Unlike JavaScript, System.Dictionary<T> is not an object with prototypical inheritance. Dictionaries provide key-value pairs, but they do not additionally "inherit" key/value pairs from any other object. Therefore, for-in and foreach-in loops are guaranteed to only loop over the keys and values specified for the dictionary itself.

Additionally, as described above, JS++ dictionary keys must be accessed with the index ([...]) operator rather than the dot (.) operator.

Difference from System.Object

System.Object is not a JavaScript "object." System.Object is the root class that all JS++ types inherit from. Unlike System.Dictionary<T>, System.Object does not provide key-value pair functionality.

Examples

Instantiation
1
2
3
import System;
 
System.Dictionary<int> dict = new System.Dictionary<int>({ a: 1, b: 2 });
Auto-boxing
1
2
3
4
5
6
import System;
 
System.Dictionary<int> employeeID = {
    "Roger": 1,
    "Anton": 2
};
Dynamically inserting keys and values into the dictionary
1
2
3
4
5
6
import System;
 
Dictionary<int> dict = {};
for(int i = 0; i < 5; ++i) {
    dict[i.toString()] = i;
}
Dynamically modifying a key/value pair in the dictionary
1
2
3
4
5
6
7
8
import System;
 
Dictionary<int> employeeID = {
    "Joe": 1,
    "Jane": 2
};
employeeID["Joe"] = 100;
employeeID["Jane"] = 200;
Iterating the keys of the dictionary
1
2
3
4
5
6
7
8
9
10
import System;
 
System.Dictionary<int> employeeID = {
    "Roger": 1,
    "Anton": 2
};
 
for(string key in employeeID) {
    Console.log("Employee Name: " + key);
}
Iterating the values of the dictionary
1
2
3
4
5
6
7
8
9
10
import System;
 
System.Dictionary<int> employeeID = {
    "Roger": 1,
    "Anton": 2
};
 
foreach(int value in employeeID) {
    Console.log(value.toString());
}
Iterating both keys and values of the dictionary
1
2
3
4
5
6
7
8
9
10
11
12
13
import System;
 
System.Dictionary<int> employeeID = {
    "Roger": 1,
    "Anton": 2
};
 
for(string key in employeeID) {
    string name = key;
    int+ id = employeeID[key];
 
    Console.log("Name: " + name + "; ID: " + (id?.toString() ?? ""));
}

Methods

  • clear

    Removes all keys and values from the dictionary.

  • contains

    Checks if the specified key is in the dictionary.

  • Dictionary (Constructor)

    Constructs a System.Dictionary<T> object.

  • insert

    Inserts a key-value pair into the dictionary.

  • isEmpty

    Checks if the dictionary is empty.

  • keys

    Returns the keys of the dictionary (optionally filtering the keys to match specified values in the key-value pair).

  • length

    Returns the number of keys in the dictionary.

  • remove

    Removes the specified key from the dictionary.

  • toExternal

    Constructs a new external object with each key-value pair of the internal Dictionary<T> converted to external (via toExternal calls on each value of the key-value pairs). If an element does not implement the System.IExportable interface, a `System.

  • toString

    Returns a string representation of the dictionary object.

  • valueOf

    Returns the dictionary object.

  • values

    Returns the values of the dictionary.

Share

HTML | BBCode | Direct Link