BlitzMax Docs -> 2D - Category -> Data -> CreateMap
Returns:A new map object
Description:Create a map
| This command creates a binary-tree (in BlitzMax called a Map/Tmap, but in other languages sometimes called a Dictionairy). These can be useful for storing objects (or strings) in a way that is fast to retrieve later on (without requiring any subsequent sorting).|
When objects are added to a Map it finds the best position in the map to store the object using a unique user-defined 'key'. The 'key' is also used to retrieve the object (or check whether a corresponding object exists).
Maps are great for dictionaries, and anything else where a unique handle/key can be used. They are fast (particularly for big lists), and often more readable than looping through a list of objects, as only a single command is needed to retrieve an object.
| Very basic example introducing the concept of|
'create map - basic example Strict Local map_items:tmap=CreateMap() 'we have a group of item Local name:String=["Han","Solo","Luke","Skywalker","Obi"] 'we insert each of them in our map 'the KEY (the name we want to attach to every item) is (in this case) the name itself 'the VALUE is (in this case) the item itself (the name of the person) For Local s$=EachIn name MapInsert map_items,s,s Next 'now we print out the content of the map 'please note that the content is ORDERD automaticcaly during the insertion 'our initial order was: Han, Solo, Luke, Skywalker, Obi 'the output now is: Han, Luke, Obi, Skywalker, Solo 'we read the map using the KEY (the name we use before) 'the map returns the KEY we used For Local r$=EachIn MapKeys(map_items) Print r Next 'we can print out the VALUES of the map - but in this case they are EQUIVALENT of 'above. the map returns the VALUES we used. For Local r$=EachIn MapValues(map_items) Print r Next
Basic example using User types
Strict Local map_items:tmap=CreateMap() Type titem Field name:String Field value:Int End Type Local times:Int For Local q:Int=1 To 10 Local it:titem=New titem times:+1 it.name=Chr(Rand(0,3)+64) 'this creates a 'name' like A, B, or C it.value=Rand(100)*10 'this creates a random value Print times+" "+it.name+" "+it.value 'we insert in out map the IT data 'our KEY is the name of the item (A, B or C) [it.name] 'out VALUES is the IT object MapInsert map_items,it.name,it Next 'note that A, B or C can be inserted into the map many times, but a MAP consider 'only ONE ITEM WITH ONE NAME 'so we can only have ONE item named 'A', ONE item named 'B', ONE item named 'C' 'and so on. 'print out the content of our map 'we have inserted 10 records... Print "~nLabels-Keys we used to insert the data~n" For Local out:String=EachIn MapKeys(map_items) Print out Next 'we should find only THREE keys-labels: A, B or C Print "~nNow print out the data/values~n" For Local data:titem=EachIn MapValues(map_items) Print data.name+" "+data.value Next 'please note one important thing: A (and B and C) stores only the LAST value added 'the data output are orderd during the MapInsert process
The following example shows
Strict Local map_items:tmap=CreateMap() Type titem Field name:String Field value:Int End Type Local times:Int For Local q:Int=1 To 10 Local it:titem=New titem times:+1 it.name=Chr(Rand(0,3)+64) 'this creates a 'name' like A, B, or C it.value=Rand(100)*10 'this creates a random value Print times+" "+it.name+" "+it.value 'we insert in out map the IT data 'our KEY is the name of the item (A, B or C) [it.name] 'out VALUES is the IT object MapInsert map_items,it.name,it Next 'Now we want to know the value of 'A' Local result:titem=Titem(MapValueForKey(map_items,"A")) 'this mean: 'find in MAP_ITEMS the item we named 'A' and returns it 'as this item is a user-type (Titem) we need to cast it to access it If result 'if the items exist! Print "A has a value of "+result.value Else Print "No item named 'A' - sorry!" End If 'And now we want to see if the maps contains or not a KEY '(remember we used STRING as KEY...but they can be any object!) Print "D exists in the Map? "+MapContains(map_items,"D" ) Print "B exists in the Map? "+MapContains(map_items,"B" ) 'the function returns 1 (TRUE) if an item with the label exists or 0 (FALSE) if not 'we can check if the map is empty Print "Is the map empty? "+MapIsEmpty(map_items) 'we can also copy in a new map it Local new_map:tmap=CopyMap(map_items) 'finally we can decide to clear it ClearMap(map_items)
BlitzMax Manual Forum
Blitz3D Equivalent Command