map
The map module introduces the Map type and functions to Lua. It provides a consistent interface for maps, which is not provided by Lua tables. In stream and record UDFs the Map, which is a type supported by the database, should be used in place of Lua tables.
To create an empty Map, you can simply call the map() function.
> local m = map()
Map()
To create an empty Map with a specified initial capacity (the default is 32), you can call the map.create() function.
> local m = map.create(1000)
Map()
If you want to initialize the Map with values, then you can provide an associative Lua Table:
> local m = map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
You can access the Map much like you do with Lua Tables:
> m['a']
1
> m.b
2
> m.b = 7
> m.b
7
Note that because assigning a nil value in a Lua table deletes the entry from the table, it is not possible to initialize a Map containing nil values via the map() function.
A map must only contain values of the following types:
Placing other Lua types - for example, functions or tables - will result in run-time errors.
Functions
map()
Creates a new Map. [Its initial capacity will be 32. If the map will contain many more entries than this, use map.create() for better performance.]
function map(t: Table?): Map
| Parameter | Returns |
|---|---|
t – (optional) Lua table containing the initial values. | The intialized Map |
Examples:
Create an empty Map:
> local m = map()
Map()
Create a new Map and initialize it via an associative Lua Table:
> local m = map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
map.create()
Creates a new Map, with a specified initial capacity. For greatest efficiency, specify a capacity roughly equal to the maximum number of elements the Map will contain (if known).
function map.create(c: integer): Map
| Parameter | Returns |
|---|---|
c – initial Map capacity. | The intialized Map |
Example:
Create an empty Map with space for 20,000 entries:
> local m = map.create(20000)
Map()
map.size()
The number of (key, value) pair entries in the Map.
function map.size(m: Map): Integer
| Parameter | Returns |
|---|---|
m – The Map to get the size of. | The number of entries in the map. |
Example:
> local m = map {a=1, b=2, c=3}
Map( "a" => 1, "b" => 2, "c" => 3 )
> map.size(m)
3
map.pairs()
Get an iterator for all (key, value) pairs in a Map.
function map.pairs(m: Map): iterator
| Parameter | Returns |
|---|---|
m – The Map to iterate over. | The iterator function |
Example:
> local m = Map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
> for key, value in map.pairs(m) do
> info("%s = %d", key, value)
> end
a = 1
b = 2
c = 3
map.keys()
Get an iterator for all keys in a Map.
function map.keys(m: Map): iterator
| Parameter | Returns |
|---|---|
m – The Map to iterate over. | The iterator function |
Example:
> local m = Map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
> for key in map.keys(m) do
> info("%s", key)
> end
a
b
c
map.values()
Get an iterator for all values in a Map.
function map.values(m: Map): iterator
| Parameter | Returns |
|---|---|
m – The Map to iterate over. | The iterator function |
Example:
> local m = Map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
> for value in map.values(m) do
> info("%d", value)
> end
1
2
3
map.remove()
Remove an entry from a Map.
function map.remove(m: Map, key: string): nil
| Parameter | Returns |
|---|---|
m – The Map to remove an entry from. | key – The key of the Map entry to remove. |
Example:
> local m = Map { a = 1, b = 2, c = 3 }
Map( "a" => 1, "b" => 2, "c" => 3 )
> map.remove(m, "b")
> m
Map( "a" => 1, "c" => 3 )
map.clone()
Create a new Map as a shallow copy of a Map. All the keys and values are not copied, but still reference the original keys and values.
function map.clone(m: Map): Map
| Parameter | Returns |
|---|---|
m – The Map to clone. | A new Map containing all entries in the map. |
Example:
> local m1 = Map { a = 1 }
Map( "a" => 1 )
> local m2 = map.clone(m1)
Map( "a" => 1 )
> m2['a'] = 2
> m2
Map( "a" => 2 )
> m1
Map ( "a" => 1 )
map.merge()
Merge two Maps, creating a new Map. When keys collide, call the merge function op to merge the values.
function map.merge(m1: Map, m2: Map, op: function): Map
| Parameter | Returns |
|---|---|
m1 – A map to be merged. | A new Map containing all merged entries of the two maps. |
m2 – Another map to be merged. | A new Map containing all merged entries of the two maps. |
op – The function to use when merging pairs with the same key. | A new Map containing all merged entries of the two maps. |
Where merge function op would take two values and return a resolved value:
function(a: Val, b: Val): Val
Example:
> local m1 = map { a = 1, b = 2 }
Map( "a" => 1, "b" => 2 )
> local m2 = map { a = 3 }
Map( "a" => 3 )
> map.merge(m1, m2, function (v1, v2)
> return v1 + v2
> end)
Map( "a" => 4, "b" => 2 )