Language: Maps

Maps are a collection of zero or more key/value pairs. These are useful for storing values that are looked up by a unique key.

Maps can be created using {} and specifying key/value pairs. Keys and values can be differing types. An optional trailing comma is allowed. Examples:

// Empty map
{}

// Map with a single value on one line
{ "key": "value" }

// Map with multiple values with differing types on multiple lines
{
    "key": "value",
    42: true,
}

Maps are unordered. When looping over a map, the key/value pairs can be returned in any order.

The set operators can be used to test for key inclusion in a map.

Accessing Elements

Map elements can be accessed with the syntax name[key]. This looks up a value by a key.

Accessing a key that doesn't exist results in undefined.

Examples:

map = { "key": "value", 42: true, }

map["key"] // "value"
map[42]    // true
map[0]     // undefined

Modifying or Adding Elements

Elements can be added or modified in a map by assigning to name[key]. If the key doesn't exist, the value is added. If the key already exists, the value is overridden.

map = { "key": "value" }

map[42] = true   // Add a new key/value
map["key"] = 12  // Modify the value of "key"

Deleting Elements

An element can be deleted from a map using the delete function.

Examples:

map = { "key": "value" }
delete(map, "key")    // map is now empty
delete(map, "other")  // no effect for non-existent key

Keys and Values

The keys and values of a map can be retrieved as lists using the keys and values functions.

Because maps are unordered, the keys and values are returned in an unspecified order. It should not be assumed that keys and values will be returned in a consistent order.

data = { "a": 2, "b": 3 }
keys(data)       // ["b", "a"]
values(data)     // [2, 3]

Map Comparison

Maps may be compared for equality. Maps are equal if they are of equal length and both their corresponding keys and values are comparable and equal.

{"foo": "bar"} is {"foo": "bar"}               // true
{"foo": "bar"} is {"baz": "bar"}               // false
{"foo": "bar"} is {"foo": "baz"}               // false
{"foo": "bar"} is {"foo": "bar", "baz": "qux"} // false
{1: "a"} is {1.0: "a"}                         // true (int/float comparable)

// also true (maps are not ordered):
{"m": {"a": "b"}, "l": ["a"]} is {"l": ["a"], "m": {"a": " b"}}