IndexTopSummaryMethods

Class Map

Map is a Collection of keys with associated value for each key.

Each pair key->value is called entry.

If you've already read Collection documentation, you should have understood that keys are in a Set (a Collection of unique elements).
If not, please read before ;)

Differences between table and Map

Map is like Lua table where indices are replaced by string like in births["Bach"] = 1685. In this example, key is the string "Bach" and the value is the number 1685.
Map is backed by Collections called keySet and values. Here are some code examples
ActionLua tableMapNotes
Creation t = {} m = Map:new(keyType, valueType, sortFunction) where keyType is "number" or "string", and valueType is "number", "string" or "table"
Add entry t["Key"] = value m:put(key, value) key must be of keyType, and value of valueType
Add multiple entries 
local source = {key1=value1, key2=value2}
local dest = {}
for k,v in source do
  dest[k] = v
end
 dest:putAll(source)
Read print(t[key]) print(m:get(key))
Contain a key? if t[key] then ... end if m:containsKey(key) then ... end
Contain a value? 
local found = false
for k,v in d do
  if v=="wanted" then found=true; breka; end
end
if found then print("Found")
else print("Not found"); end
 
if m:containsValue(wanted) then
  print("Found")
else print("Not found"); end
Get size getn(t) is bocus: 
local t = {Key1=1, key2=2}
print(getn(t)) --> 0
 m:size()
Browse 
local t = {key1=1, key2=2}
for k,v in datas do print(k.."="..v) end

Backward browsing impossible 
m:iterator()
while m:hasNext() do
  plocal k,v = m:next()
  print(k.."="..v)
end

Backward browsing: m:reverseIterator()

Summary

Return typeFunction and summary
Mapnew(string keyType, string valueType, function sortFunction)
Create a new Map.
keyType, valueTypeceilingEntry(keyType key)
Returns key and value associated with the least key greater than or equal to the given key, or nil,nil if there is no such key.
keyTypeceilingKey(keyType key)
Returns the least key greater than or equal to the given key, or nil if there is no such key.
 clear()
Empty the map, remove all keys and values
boolcontainsKey(keyType key)
Does Map already contains the given key?
boolcontainsValue(valueType value)
Does Map already contains the given value?
 debug()
Debug a structure of this Map in console, only if LOG_LEVEL = LOG_LEVEL_DEBUG.
keyType, valueTypefirstEntry()
Returns the first (least if Map is sorted) entry (key and value) of this Map, or nil,nil if the Map is empty.
keyTypefirstKey()
Returns the first (least if Map is sorted) key of this Map, or nil if the Map is empty.
keyType, valueTypefloorEntry(keyType key)
Returns key and mapped value associated with the greatest key less or equal than the given key, or nil,nil if there is no such key.
keyTypefloorKey(keyType key)
Returns the greatest key less or equal than the given key, or nil if there is no such key.
valueTypeget(key)
Returns the value associated to the given key, or nil if this map doesn't contains it.
valueTypegetOrDefault(keyType key, valueType defaultValue)
Returns the value associated to the given key, or defaultValue if this map doesn't contains it.
?hasNext(string iteratorName)
While iterating, is there a next entry?
MapheadMap(keyType toKey, bool inclusive)
Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive = true) toKey.
keyType, valueTypehigherEntry(keyType key)
Returns entry (key,value) of the least key greater than the given key, or nil,nil if there is no such key.
keyTypehigherKey(keyType key)
Returns the least key greater than the given key, or nil if there is no such key.
boolisEmpty()
Is this Map empty?
 iterator(string iteratorName)
Starts or restarts an iterator on the Map.
CollectionkeySet()
Returns a Set view of the keys contained in this Map.
keyType, valueTypelastEntry()
Returns the last (greatest if Map is sorted) entry (key,value) of this Map, or nil,nil if this Map is empty.
keyType, keyType, valueTypelastKey()
Returns the last (greatest if Map is sorted) key of this Map, or nil if Map is empty.
keyType, valueTypelowerEntry(keyType key)
Returns key,value of the greatest key less than the given key, or nil,nil if there is no such key.
keyTypelowerKey(keyType key)
Returns the greatest key less than the given key, or nil if there is no such key.
intmerge(keyType key, valueType value)
If this Map doesn't contains the given key, insert the given key and value.
?next(string iteratorName)
While iterating, returns next entry if :hasNext(), nil,nil otherwise.
 print()
Prints a debug structure of the Map in console, if you want it prints only if LOG_LEVEL = LOG_LEVEL_DEBUG, use :debug() instead.
intput(keyType key, valueType value)
Insert a new entry (the given key,value) into this Map.
intputAll(anotherMap)
Put all entries (key,value pairs) of anotherMap into this Map.
intremove(keyType key, valueType value)
Removes the entry for the given key.
intreplace(keyType key, valueType oldValue, valueType newValue)
Replaces the entry if this Map contains key, never inserts new entry.
 reverseIterator(string iteratorName)
Starts or restarts a reverse iterator on the Map.
intsize()
Returns the number of entries in this Map.
MapsubMap(keyType fromKey, bool fromInclusive, keyType toKey, bool toInclusive)
Returns a view of the portion of this Map whose keys range from fromKey to toKey.
MaptailMap(keyType fromKey, bool inclusive)
Returns a view of the portion of this Map whose keys are greater than (or equal to, if inclusive==true) fromKey.
Collectionvalues()
Returns a Collection view of the values contained in this Map, in the same order than the keys.

Methods

Map:new(string keyType, string valueType, function sortFunction)

Create a new Map.

ParameterTypeDefaultDescription
keyTypestring"string""number" or "string"
valueTypestring"string""number", "string" or "table"
sortFunctionfunctionnilkeys sorting function can be provided, else keys stay in insertion order
Return
Map: A new empty Map
Error
if keyType or valueType have wrong values.
Example 
local m = Map:new("string", "number")
local sortedMap = Map:new("number", "string", SORT_ASCENDING)

Map:put(keyType key, valueType value)

Insert a new entry (the given key,value) into this Map.

If key already exists, its old value is replaced by the given value.

ParameterTypeDefaultDescription
keykeyType Key to insert or update, number or string
valuevalueType New value
Return
int: Always 1
Errors
if type(key) doesn't match constructor keyType parameter
if type(value) doesn't match constructor valueType parameter
Example 
local m = Map:new("string", "number")
m:put("Bach", 1685); m:put("Mozart", 1756)

Map:putAll(anotherMap)

Put all entries (key,value pairs) of anotherMap into this Map.

If some key already exist, their associated value are replaced.

ParameterTypeDefaultDescription
anotherMap  A table[key]=value, or a Map
Return
int: Number of inserted/updated pairs, = anotherMap:size().
Errors
if anotherMap is not a table nor a Map.
if anotherMap entries (key,value) are not compatibles with constructor keyType and valueType parameters.
Example 
local m = Map:new("string", "number")
local t = {}; t.Bach = 1685; t["Mozart"] = 1756
m:putAll(t)

Map:clear()

Empty the map, remove all keys and values

Map:containsKey(keyType key)

Does Map already contains the given key?

ParameterTypeDefaultDescription
keykeyType number or string
Return
bool: true, or nil (for false)
Error
if type(key) doesn't match constructor keyType parameter
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
print(m:containsKey("Bach")) --> true
print(m:containsKey("HAydn")) --> false

Map:containsValue(valueType value)

Does Map already contains the given value?

ParameterTypeDefaultDescription
valuevalueType number, string or table
Return
bool: true, or nil (for false)
Errors
if type(value) doesn't match constructor valueType parameter
if values of this Map are not comparables
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
print(m:containsValue(1756)) --> true
print(m:containsValue(1789)) --> false

Map:get(key)

Returns the value associated to the given key, or nil if this map doesn't contains it.

ParameterTypeDefaultDescription
key  number or string
Return
valueType: A value or nil if key is not found
Error
if type(key) doesn't match constructor keyType parameter
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
print(m:get("Bach")) --> 1685
print(m:get("Haydn")) --> nil

Map:getOrDefault(keyType key, valueType defaultValue)

Returns the value associated to the given key, or defaultValue if this map doesn't contains it.

ParameterTypeDefaultDescription
keykeyType number or string
defaultValuevalueType number, string or table
Return
valueType: A value or defaultValue if key is not found
Errors
if type(key) doesn't match constructor keyType parameter
if type(defaultValue) doesn't match constructor valueType parameter
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
print(m:getOrDefault("Bach", 1234)) --> 1685
print(m:getOrDefault("Haydn", 1234)) --> 1234

Map:isEmpty()

Is this Map empty?

Return
bool: true, or nil (for false)

Map:keySet()

Returns a Set view of the keys contained in this Map.

A Set is a Collection with unique elements, sorted or not.

Return
Collection: A Collection containing all keys

Map:merge(keyType key, valueType value)

If this Map doesn't contains the given key, insert the given key and value.

Else, no change is done, the given value will not replace the old associated to key.

ParameterTypeDefaultDescription
keykeyType The key to insert if not found, number or string
valuevalueType The value
Return
int: 1 if key,value is inserted, 0 if key already exists in this Map.
Errors
if type(key) doesn't match constructor keyType parameter
if type(value) doesn't match constructor valueType parameter
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
print(m:get("Vivaldi")) --> nil
-- add Vivaldi if not already in map
m:merge("Vivaldi", 1678) --> return 1
print(m:get("Vivaldi")) --> 1678
-- merge with a bogus date
m:merge("Bach", 1785) --> return 0
print(m:get("Bach")) --> 1685, not replaced

Map:remove(keyType key, valueType value)

Removes the entry for the given key.

If the given value is not nil, removes the entry only if its value equals the given value.

ParameterTypeDefaultDescription
keykeyType number or string
valuevalueTypenilA value to remove only if equals, or nil to remove without testing equality check
Return
int: 0 if not removed, 1 if removed.
Errors
if type(key) doesn't match constructor keyType parameter
if type(value) doesn't match constructor valueType parameter
if value~=nil and values of this Map are not comparables
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1685, Mozart=1756})
m:remove("Vivaldi") --> return 0
m:remove("Bach", 1234) --> return 0, not removed because Bach value is 1685
m:remove("Bach", 1685) --> return 1
m:remove("Mozart") --> return 1

Map:replace(keyType key, valueType oldValue, valueType newValue)

Replaces the entry if this Map contains key, never inserts new entry.

If oldValue~=nil, replaces, only if the entry's value equals oldValue.

ParameterTypeDefaultDescription
keykeyType number or string
oldValuevalueTypenilA value to replace only if equals, nil to replace without equality check.
newValuevalueType The new value
Return
int: 0 if not replaced, 1 if replaced.
Errors
if type(key) doesn't match constructor keyType parameter
if type(oldValue) or type(newValue) don't match constructor valueType parameter
if oldValue~=nil and values of this Map are not comparables
Example 
local m = Map:new("string", "number")
m:putAll({Bach=1785, Mozart=1756})
-- Oops! wrong Bach birth date
m:replace("Bach", nil, 1685) --> return 1, replaced without equality check
m:replace("Mozart", 1757, 1234) --> return 0, Mozart value is 1756, not 1757
m:replace("Mozart", 1756, 1234) --> return 1

Map:size()

Returns the number of entries in this Map.

Return
int: 0 or greater

Map:values()

Returns a Collection view of the values contained in this Map, in the same order than the keys.

Return
Collection: A Collection that can contain multiple times the same value.

Map:ceilingEntry(keyType key)

Returns key and value associated with the least key greater than or equal to the given key, or nil,nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType to search ceiling, number or string
Returns
keyType: Key or nil if map is empty
valueType: Value, or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:ceilingKey
Map:floorEntry
Map:higherEntry
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:ceilingEntry("apricot")) --> banana 5
print(m:ceilingEntry("banana")) --> banana 5
print(m:ceilingEntry("pear")) --> nil nil

Map:ceilingKey(keyType key)

Returns the least key greater than or equal to the given key, or nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search for ceiling, number or string
Return
keyType: A key or nil
Error
if type(key) doesn't match constructor keyType parameter
See
Map:ceilingEntry
Map:floorKey
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:ceilingKey("apricot")) --> banana
print(m:ceilingKey("banana")) --> banana
print(m:ceilingKey("pear")) --> nil

Map:floorEntry(keyType key)

Returns key and mapped value associated with the greatest key less or equal than the given key, or nil,nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search floor, number or string
Returns
keyType: Key or nil if map is empty
valueType: Value, or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:floorKey
Map:ceilingEntry
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:floorEntry("apricot")) --> apple 3
print(m:floorEntry("apple")) --> apple --> apple 3
print(m:floorEntry("pear")) --> kiwi 8
print(m:floorEntry("aaa")) -> nil nil

Map:floorKey(keyType key)

Returns the greatest key less or equal than the given key, or nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search for floor, number or string
Return
keyType: A key or nil
Error
if type(key) doesn't match constructor keyType parameter
See
Map:floorEntry
Map:ceilingKey
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:floorKey("apricot")) --> apple
print(m:floorKey("apple")) --> apple
print(m:floorKey("pear")) --> kiwi
print(m:floorKey("aaa")) -> nil

Map:higherEntry(keyType key)

Returns entry (key,value) of the least key greater than the given key, or nil,nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search higher, number or string
Returns
keyType: Key or nil if map is empty
valueType: Value, or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:higherKey
Map:lowerEntry
Map:ceilingEntry
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:higherEntry("apricot")) --> banana 5
print(m:higherEntry("banana")) --> kiwi 8
print(m:higherEntry("pear")) --> nil nil

Map:higherKey(keyType key)

Returns the least key greater than the given key, or nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search for higher, number or string
Return
keyType: Key or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:higherEntry
Map:lowerKey
Map:ceilingKey
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:higherKey("apricot")) --> banana
print(m:higherKey("banana")) --> kiwi
print(m:higherKey("pear")) --> nil

Map:lowerEntry(keyType key)

Returns key,value of the greatest key less than the given key, or nil,nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search higher, number or string
Returns
keyType: Key or nil if map is empty
valueType: Value, or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:lowerKey
Map:higherEntry
Map:floorEntry
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:lowerEntry("apricot")) --> apple 3
print(m:lowerEntry("banana")) --> apple 3
print(m:lowerEntry("apple")) --> nil nil

Map:lowerKey(keyType key)

Returns the greatest key less than the given key, or nil if there is no such key.

ParameterTypeDefaultDescription
keykeyType Key to search higher, number or string
Return
keyType: Key or nil if map is empty
Error
if type(key) doesn't match constructor keyType parameter
See
Map:lowerEntry
Map:higherKey
Map:floorKey
Example 
local m = Map:new("string","number")
m:put("apple", 3); m:put("banana", 5); m:put("kiwi", 8)
print(m:lowerKey("apricot")) --> apple
print(m:lowerKey("banana")) --> apple
print(m:lowerKey("apple")) --> nil

Map:firstEntry()

Returns the first (least if Map is sorted) entry (key and value) of this Map, or nil,nil if the Map is empty.

Returns
keyType: Key, or nil if map is empty
valueType: Value, or nil if map is empty
See
Map:firstKey
Map:lastEntry
Example 
local m = Map:new("string", "number") -- no sorting
m:putAll({Vivaldi=1678, BAch=1685, Mozart=1756})
print(m:firstEntry()) --> Vivaldi 1678
m = Map:new("string", "number", SORT_ASCENDING) -- key are sorted alphabetically
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:firstEntry()) --> Bach 1685

Map:firstKey()

Returns the first (least if Map is sorted) key of this Map, or nil if the Map is empty.

Return
keyType: key, or nil if Map is empty
See
Map:firstEntry
Map:lastKey
Example 
local m = Map:new("string", "number") -- no sorting
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:firstKey()) --> Vivaldi
m = Map:new("string", "number", SORT_ASCENDING) -- key are sorted alphabetically
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:firstKey()) --> Bach

Map:lastEntry()

Returns the last (greatest if Map is sorted) entry (key,value) of this Map, or nil,nil if this Map is empty.

Returns
keyType: Key, or nil if map is empty
valueType: Value, or nil if map is empty
See
Map:LastKey
Map:firstEntry
Example 
local m = Map:new("string", "number") -- no sorting
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:lastEntry()) --> Mozart 1756
m = Map:new("string", "number", SORT_ASCENDING) -- key are sorted alphabetically
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:lastEntry()) --> Vivaldi 1678

Map:lastKey()

Returns the last (greatest if Map is sorted) key of this Map, or nil if Map is empty.

Returns
keyType: a key, or nil
keyType: Key, or nil if map is empty
valueType: Value, or nil if map is empty
See
Map:LastEntry
Map:firstKey
Example 
local m = Map:new("string", "number") -- no sorting
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:lastKey()) --> Mozart
m = Map:new("string", "number", SORT_ASCENDING) -- key are sorted alphabetically
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
print(m:lastKey()) --> Vivaldi

Map:headMap(keyType toKey, bool inclusive)

Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive = true) toKey.

ParameterTypeDefaultDescription
toKeykeyType  
inclusiveboolfalse 
Return
Map: A Map, can be empty
Error
if type(toKey) doesn't match constructor keyType parameter
See
Map:tailMap
Map:subMap
Example 
local m = Map:new("string", "number") -- works even if map is unsorted
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
local h = m:headMap("Bach", false) --> h is empty
h = m:headMap("Bach", true) --> h contains Bach

Map:subMap(keyType fromKey, bool fromInclusive, keyType toKey, bool toInclusive)

Returns a view of the portion of this Map whose keys range from fromKey to toKey.

ParameterTypeDefaultDescription
fromKeykeyType  
fromInclusivebooltrueInclude fromKey in returned Map?
toKeykeyType  
toInclusiveboolfalseInclude toKey in returned Map?
Return
Map: A new Map, can be empty
Errors
if type(fromKey) or type(toKey) doesn't match constructor keyType parameter
if toKey < fromKey
See
Map:headMap
Map:tailMap
Example 
local m = Map:new("string", "number") -- work even if unsorted
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
local s = m:subMap("Bach", false, "Purcell", false) --> s contains Mozart
s = m:subMap("Bach", true, "Purcell", true) --> s contains Bach and Mozart
s = m:subMap("Haydn", true, "Lully", true) --> s is empty

Map:tailMap(keyType fromKey, bool inclusive)

Returns a view of the portion of this Map whose keys are greater than (or equal to, if inclusive==true) fromKey.

ParameterTypeDefaultDescription
fromKeykeyType  
inclusiveboolfalseInclude fromKey in returned Map?
Return
Map: A new Map, can be empty
Error
if type(fromKey) doesn't match constructor keyType parameter
See
Map:headMap
Map:subMap
Example 
local m = Map:new("string", "number") -- works even if unsorted
m:putAll({Vivaldi=1678, Bach=1685, Mozart=1756})
local t = m:tailMap("Bach", false) --> t contains Mozart and Vivaldi
t = m:tailMap("Vivaldi", false) --> t is empty
t = m:tailMap("Vivaldi", true) --> t contains Vivaldi

Map:iterator(string iteratorName)

Starts or restarts an iterator on the Map.

An iterator is a convenient way to browse the Map from first to last entry with :hasNext() and :next() methods.
You can provide an iteratorName to run multiple iterators simultaneously, else the result would be hazardous.

ParameterTypeDefaultDescription
iteratorNamestringnil 
See
Map:reverseIterator
Map:hasNext
Map:next

Map:reverseIterator(string iteratorName)

Starts or restarts a reverse iterator on the Map.

A reverse iterator is a convenient way to browse the Map from last to first entry with :hasNext() and :next() methods.
You can provide an iteratorName to run multiple iterators simultaneously, else the result would be hazardous.

ParameterTypeDefaultDescription
iteratorNamestringnil 
See
Map:iterator
Map:hasNext
Map:next

Map:hasNext(string iteratorName)

While iterating, is there a next entry?

You can provide an iteratorName to run multiple iterators simultaneously, else the result would be hazardous.

ParameterTypeDefaultDescription
iteratorNamestringnil 
Return
nil (for false) if end of Map is reached, true if there are still some entries to iterate
See
Map:iterator
Map:reverseIterator
Map:next

Map:next(string iteratorName)

While iterating, returns next entry if :hasNext(), nil,nil otherwise.

You can provide an iteratorName to run multiple iterators simultaneously, else the result would be hazardous.

ParameterTypeDefaultDescription
iteratorNamestringnil 
Return
key,value or nil,nil
See
Map:iterator
Map:reverseIterator
Map:hasNext

Map:print()

Prints a debug structure of the Map in console, if you want it prints only if LOG_LEVEL = LOG_LEVEL_DEBUG, use :debug() instead.

Map:debug()

Debug a structure of this Map in console, only if LOG_LEVEL = LOG_LEVEL_DEBUG.