BlitzMax/Modules/Data structures/Maps

A map contains a set of key/value pairs. The keys and values may be any object type. A Red-Black Tree is used as the data structure.

For ordered collections of objects, see Linked lists.

Functions

CreateMap

Function CreateMap:TMap()

Description: Create a map

Returns: A new map object

ClearMap

Function ClearMap( map:TMap )

Description: Clear a map

Information: ClearMap removes all keys and values from map

MapIsEmpty

Function MapIsEmpty( map:TMap )

Description: Check if a map is empty

Returns: True if map is empty, otherwise false

MapInsert

Function MapInsert( map:TMap,key:Object,value:Object )

Description: Insert a key/value pair into a map

Information: If map already contained key, its value is overwritten with value.

Example:

' mapinsert.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")

Print MapIsEmpty(map)

ClearMap(map)

Print MapIsEmpty(map)

MapValueForKey

Function MapValueForKey:Object( map:TMap,key:Object )

Description: Find a value given a key

Returns: The value associated with key

Information: If map does not contain key, a Null object is returned.

Example:

' mapvalueforkey.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")

Print String(MapValueForKey(map, "Key 1"))

MapContains

Function MapContains( map:TMap,key:Object )

Description: Check if a map contains a key

Returns: True if map contains key

Example:

'mapcontains.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")

Print MapContains(map, "Key 1")
Print MapContains(map, "Key 2")

MapRemove

Function MapRemove( map:TMap,key:Object )

Description: Remove a key/value pair from a map

Comment: Unlike the Remove method for TMap, this function does not return whether the key/value pair was removed or not.

Example:

' mapremove.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")

Print MapContains(map, "Key 1")

MapRemove(map, "Key 1")

Print MapContains(map, "Key 1")

MapKeys

Function MapKeys:TMapEnumerator( map:TMap )

Description: Get map keys

Returns: An iterator object

Information: The object returned by MapKeys can be used with EachIn to iterate through the keys in map.

Example:

' mapkeys.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")
MapInsert(map, "Key 2", "Value 2")

Local obj:Object
For obj = EachIn MapKeys(map)
	Print(String(obj) + "," + String(MapValueForKey(map, obj)))
Next

MapValues

Function MapValues:TMapEnumerator( map:TMap )

Description: Get map values

Returns: An iterator object

Information: The object returned by MapValues can be used with EachIn to iterate through the values in map.

Example:

' mapvalues.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")
MapInsert(map, "Key 2", "Value 2")

Local obj:Object
For obj = EachIn MapValues(map)
	Print String(obj)
Next

CopyMap

Function CopyMap:TMap( map:TMap )

Description: Copy a map

Returns: A copy of map

Example:

' copymap.bmx

Local map:TMap = CreateMap()

MapInsert(map, "Key 1", "Value 1")

Local map2:TMap = CopyMap(map)

Print String(MapValueForKey(map2, "Key 1"))