Associative maps

Note: This feature is for ZScript only.

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 (New from 4.11.0)

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 (New from 4.11.0)

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

• ValueType GetIfExists (KeyType key) const (New from 4.11.0)

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

• ValueType, bool CheckValue (KeyType key) const (New from 4.11.0)

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.

Alternative iteration

(Pull request #2217 only)
foreach can be used similar to how it's done with dynamic arrays. See examples below.

foreach([key,] value : map/mapiterator)
{
    //...
}

Examples

Iteration can be done this way as an alternative.

Map<String, int> testmap;
		
testmap.Insert("123",123);
testmap.Insert("456",456);
testmap.Insert("789",789);

foreach( k , v : testmap )
{
	console.printf("k = '"..k.."' v = "..v);
}

foreach( v : testmap )
{
	console.printf("v = "..v);
}

MapIterator<String, int> testmapIt;

testmapIt.Init(testmap);

foreach( k , v : testmapIt )
{
	console.printf("k = '"..k.."' v = "..v);
}

foreach( v : testmapIt )
{
	console.printf("v = "..v);
}