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"))