Associative maps

Note: This feature is for ZScript only.

(New from 4.10.0)

Associative maps are similar to their C++ counterparts, storing a key and a value associated with it. Considered a successor to ZScript's Dictionary class, these are capable of storing more types of data as keys and values rather than being limited to just strings.

Declaration

Maps can be defined as such:

Map<k,v> MyMap;

Where k is the key variable type, and v is the value variable type.

• Key Types can only be strings or integrals (int/name/TextureID/etc)
• Value Types can be any type accepted by dynamic arrays.

Example:

Map<Int, Object> ClassMapper;

Map functions

• void Copy (out Map<KeyType, ValueType> other)

Copy the contents of another map into this, replacing the current contents.

• void Move (out Map<KeyType, ValueType> other)

Move the contents of another map into this, replacing the current contents and leaving the other map empty.

• void Swap (out Map<KeyType, ValueType> other)

Swap the contents of both maps.

• void Clear ()

Clear the current contents.

• uint CountUsed ()
• uint CountUsed () const (development version 698bd25 only)

Returns the number of entries in the map.

• ValueType Get (KeyType key)

Returns the value for the key. If no value exists, an empty one is created.

• bool CheckKey (KeyType key)
• bool CheckKey (KeyType key) const (development version 698bd25 only)

Returns true if a value exists for the key, false if it does not.

• ValueType GetIfExists (KeyType key) (development version decba68 only)
• ValueType GetIfExists (KeyType key) const (development version 698bd25 only) (current)

Returns the default value without creating a new key if it does not exist.

• ValueType CheckValue (KeyType key, out bool exists) (development version decba68 only)
• ValueType CheckValue (KeyType key, out bool exists) const (development version 698bd25 only)
• ValueType, bool CheckValue (KeyType key) const (development version 4c7e9c6 only) (current)

This is the same as GetIfExists, but also returns true or false depending on the key's existence.

• void Insert (KeyType key, ValueType value)

Sets the key to the value given, replacing it if it already exists.

• bool InsertNew (KeyType key)

Sets the key to an empty value, replacing it if it already exists.

• void Remove (KeyType key)

Removes a key if it exists.

MapIterator functions

• bool Init (out Map<KeyType, ValueType> other)

Starts iteration for the map given, returning true if valid. Next must be called to get the first value.

• bool ReInit ()

Restarts iteration for the last map used, returning true if valid. Next must be called to get the first value.

• bool Valid ()

Returns true if the iterator is currently valid. Modifying or deleting the map it is iterating on makes it invalid.

• bool Next ()

Advances the position and returns true if there are elements left.

Warning: Only safe to call if valid.

• KeyType GetKey ()

Returns the key for the current element. Only safe to call if both Next and Valid return true.

• ValueType GetValue ()

Returns the value for the current element. Only safe to call if both Next and Valid return true.

• void SetValue (ValueType value)

Sets the value for the current element. Only safe to call if both Next and Valid return true.

Examples

Note: This article lists no examples. If you make use of this feature in your own project(s) or know of any basic examples that could be shared, please add them. This will make it easier to understand for future authors seeking assistance. Your contributions are greatly appreciated.