Skip to main content

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