Dictionary

Dictionary is a ZScript class that provides key-value storage. Both keys and values are strings. One way to think of this is that this is a dynamic array of strings, but the indices (keys) are also strings.

Only one value is allowed for a given key.

Methods

Static

• Dictionary Create ()

Creates an empty dictionary.

• Dictionary FromString (String s)

Deserializes a dictionary from string s, which must be either empty or in the form {"key1" : "value1", "key2" : "value2", etc.} (remember to escape the quotes!). For example,

 Dictionary dict = Dictionary.FromString( "{\"key1\" : \"value1\", \"key2\" : \"value2\"}" );

will create a dictionary with keys "key1" and "key2", with associated values "value1" and "value2", respectively.

Non-static

• void Insert (String key, String value)

Inserts a new key-value pair into the dictionary.

• void Remove (String key)

Removes a key-value pair from the dictionary.

• String At (String key) const

Returns the value for the specified key.

• String ToString () const

Serializes a dictionary to a string, in the form {"key1":"value1", "key2":"value2", etc.}. The string returned has the correct form to be used for FromString. Note that an empty dictionary will return "{}".

Iterating over Dictionaries

To iterate over a dictionary, use DictionaryIterator class. The order in which the key-value pairs are accessed is not specified.

DictionaryIterator is not serializable to save files. To make DictionaryIterator a class member, use transient keyword.

DictionaryIterator Methods

• static DictionaryIterator Create (Dictionary dict)

Creates an iterator object for dictionary dict.

• bool Next ()

Returns false if there are no more entries in the dictionary. Otherwise, returns true. While it returns true, get key and value for the current entry with Key and Value() functions.

• String Key () const

Returns the key for the current dictionary entry. Do not call this function before calling Next.

• String Value () const

Returns the value for the current dictionary entry. Do not call this function before calling Next.

Examples

Basic usage

 Dictionary descriptions = Dictionary.Create();
 descriptions.Insert("Cyberdemon", "Towering, hellish marriage of demon flesh and technology.");
 String cyberdemonDescription = descriptions.At("Cyberdemon")); //equal to "Towering, hellish marriage of demon flesh and technology."

String Conversions

Dictionary to String

 Dictionary descriptions = Dictionary.Create();
 descriptions.Insert("Cyberdemon", "Towering, hellish marriage of demon flesh and technology.");
 descriptions.Insert("Arch-Vile", "A fast, deadly sorcerer, able to resurrect the dead.");
 
 String serializedDescriptions = descriptions.ToString(); // Creates the same string as the code below (up to spaces between strings, which do not matter).

String to Dictionary

 String serializedDescriptions = "{
     \"Cyberdemon\" : \"Towering, hellish marriage of demon flesh and technology.\",
     \"Arch-Vile\"  : \"A fast, deadly sorcerer, able to resurrect the dead.\"
 }"; // Spaces between strings are for formatting the code; it does not matter for ToString/FromString.
 Dictionary descriptions = Dictionary.FromString(serializedDescriptions); // Creates the same dictionary as the code above

Iterating

 Dictionary descriptions = Dictionary.Create();
 descriptions.Insert("DoomImp", "Human-sized, humanoid, fireball-flinging monster.");
 descriptions.Insert("Zombieman", "A space marine which has been turned into a zombie.");
 descriptions.Insert("Cacodemon", "Bumpy red monsters with large spherical bodies.");
 descriptions.Insert("Cyberdemon", "Towering, hellish marriage of demon flesh and technology.");
 
 DictionaryIterator i = DictionaryIterator.Create(descriptions);
 while (i.Next())
 {
   Console.Printf("%s: %s", i.Key(), i.Value());
 }

Console output:

 Zombieman: A space marine which has been turned into a zombie.
 Cacodemon: Bumpy red monsters with large spherical bodies.
 Cyberdemon: Towering, hellish marriage of demon flesh and technology.
 DoomImp: Human-sized, humanoid, fireball-flinging monster.

See also

• Associative maps