Dictionaries

Dictionaries are collections containing a sorted list of keys and associated values. East dictionaries are dynamically sized and can contain an arbitrary number of entries. In JavaScript and some other programming languages dictionaries are known as a Map.

Dictionary values and types

The East type for dictionaries with keys of type K and values of type T is DictType(K, T). Currently K is restricted to being StringType. There are many different dictionary types, like DictType(StringType, IntegerType) and DictType(StringType, DateTimeType). The EDK accepts standard JavaScript Maps as values for DictType.

East type	Example value (JavaScript)	East object notation
DictType(StringType, BooleanType)	new Map()	{:}
DictType(StringType, BooleanType)	new Map([["a", true], ["b", false]])	{"a": true, "b": false,}

Constructing dictionaries

Dictionaries are constructed with the NewDict expression. The first argument to NewDict is the type of key that can be contained within the dictionary. The second is the type of value that can be associated with each key. Subsequent to that, you can optionally provide a two lists of expressions to populate the keys and the values in the new dictionary, respectively.

East function	Description	Example usage	Result
NewDict	Create a new empty dictionary mapping strings to Booleans	NewDict(StringType, BooleanType)	{:}
NewDict	Create a new dictionary with two entries	NewDict(StringType, BooleanType, [Const("a"), Const("b")], [Const(true), Const(false)])	{"a": true, "b": false,}

Basic operations on dictionaries

You can query whether a key exists in a dictionary with In, and get the number of entries with Size. You can create a set of keys with Keys. You can fetch a value from a dictionary with its key (or index) using Get. If the key might not exist, you can specify a default value. If you do not specify a default value and they key does not exist, a runtime error will result.

You can modify arrays by inserting, updating or deleting elements. Arrays in East are immutable. The input dictionary will not be modified; instead a new one will be returned.

For brevity, in the table below the value dict is Const(new Map([["a", true], ["b", false]])).

East function	Description	Example usage	Result
Size	Get the number of entries in a dictionary	Size(dict)	2
Keys	Return the set of keys in a dictionary	Keys(dict)	{"a", "b",}
In	Determine if a key is in a dictionary	In(dict, "a")	true
Get	Fetch a value from a dictionary (error if key not exist)	Get(dict, "a")	true
Get	Fetch a value from a dictionary (with default if key not exist)	Get(dict, "c", false)	false
Insert	Insert an entry into a dictionary	Insert(dict, "c", true)	{"a": true, "b": false, "c": true,}
Update	Update an existing value in a dictionary	Update(dict, "b", true)	{"a": true, "b": true,}
Delete	Delete a entry from a dictionary	Delete(dict, "a")	{"b": true,}

Advanced dictionary operations

You can apply dictionary transformations with with Filter, FilterMap, ToDict and Reduce. These are covered in detail in later sections.

Equality and ordering

Two dictionaries are equal if they contain the same number of entries, the same set of keys, and and each value associated with a given key is equal.

Ordering of dictionaries is defined lexically. The first entries are compared, then the second, until we reach the end. For each entry, we first compare the keys and then the values. If one dictionary is the "prefix" of another, then it is lesser.

Representation

Dictionaries are represented in East's canonical JSON representation as JSON arrays of { key, value } objects. They are printed by Print in East's object notation with {} delimiters and comma seperated values (including a trailing comma). An empty dictionary is printed as {:} to disambiguate it from a set.

Next steps

Continue to the next tutorial to understand how to filter collections of data with East and Elara.