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:

integer
string
bytes
list
map

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 )