Module std.prototype.orderedmap

Ordered Map Prototype.

This module returns a table of ordered map operators, as well as the prototype for an OrderedMap container object.

An OrderedMap is a table that remembers the order in which its keys were first added. Fields are read and written as for any table, and a new key goes to the end, while writing the value of a key that is already there keeps it in its place.

A map is not a list and it has no length: # and len give the length of the sequence part of its fields, not the number of actual keys. Count the keys with size.

To remove a key, use delete. The remaining keys keep their order, and a key that is appended again is put at the end. Writing nil to a field or using rawset bypasses the OrderedMap metadata bookkeeping leaving stale keys until updated by appending again or the whole map is copied.

A key can be any value but nil, and its value can be any value but nil. While the entries are the fields of the object itself, the entry order is held in the metatable of each object.

Write the entries of a new map as a list of tables of one pair each:

local OrderedMap = require 'std.prototype.orderedmap'.prototype
local build = OrderedMap {{core = 'core.c'}, {util = 'util.c'}}
build.extra = 'extra.c'
for name, source in elems(build) do
   print(name, source)      --> core core.c, util util.c, extra extra.c
end

In addition to the functionality described here, OrderedMap containers also have all the methods and metamethods of the prototype.container.prototype (except where overridden here).

Prototype Chain

table
 `-> Container
      `-> OrderedMap

Objects

prototype OrderedMap prototype object.

Metamethods

__call (t) OrderedMap object initialisation.
__newindex (key, value) Set the value of a key that is new to the map.
__pairs () Iterate over the keys and values, in order.
__tostring () Return a string representation of this map.

Module Functions

delete (om, key) Remove a key from a map.
entries (om) The entries of a map, as a list of tables of one pair each.
elems (om) Iterate over the keys and values of a map, in order.
get (om, key) The value of a key.
keys (om) The keys of a map, in order.
merged (...) Make a new map of the entries of the maps given.
mapvalues (om, fn) Make a new map of the values of a map, with a function applied.
pluck (om, keylist) Make a new map of just some of the entries of a map.
set (om, key, value) Set the value of a key, or remove it with nil.
size (om) The number of keys in a map.
values (om) The values of a map, in the order of its keys.


Objects

prototype
OrderedMap prototype object.

Fields:

  • _type string object name (default 'OrderedMap')

See also:

Usage:

    local OrderedMap = require 'std.prototype.orderedmap'.prototype
assert(prototype.type(OrderedMap) == 'OrderedMap')

Metamethods

__call (t)
OrderedMap object initialisation.

Returns a new OrderedMap with the entries of this one, and then those of the list t of tables of one pair each, in order; where a key is written more than once the last value replaces the first, in place. A field of t that is named with a leading underscore, such as _type, is a field of the metatable instead, its n field, as entries makes, is ignored, and any other is an error.

A type that is derived with an _init function is called with the new map, which has the entries of the one called, and then all the arguments, as Container's _init is, in place of all that, and returns the map. As for Container, deriving another type from one with an _init calls it with the table that describes the new type, so it must handle fields that start with an underscore.

Parameters:

  • t table entries, and fields of the metatable

Returns:

    OrderedMap a new map

Usage:

    local build = OrderedMap {{core = 'core.c'}, {util = 'util.c'}}
local Config = OrderedMap {_type = 'Config', _init = function(new, name)
   new.name = name
   return new
end}
local config = Config 'demo'
__newindex (key, value)
Set the value of a key that is new to the map. A new key goes to the end. A field that is already there is written without this, and keeps its place.

Parameters:

  • key a key
  • value the value

Usage:

    om[key] = value
__pairs ()
Iterate over the keys and values, in order. The pairs of std.normalize honors it in every Lua, and the host's pairs in Lua 5.2 and later; elems does the same.

Usage:

    for key, value in pairs(om) do print(key, value) end
__tostring ()
Return a string representation of this map.

Returns:

    string the keys and values in order

Usage:

    --> OrderedMap {b=1, a=2}
print(OrderedMap {{b = 1}, {a = 2}})

Module Functions

delete (om, key)
Remove a key from a map.

Parameters:

  • om OrderedMap a map
  • key a key

Returns:

    OrderedMap om, without key

Usage:

    delete(om, 'old')
entries (om)
The entries of a map, as a list of tables of one pair each. This is the form that the constructor takes.

Parameters:

  • om OrderedMap a map

Returns:

    table the entries in order, with their number in field n

Usage:

    --> {{b = 1}, {a = 2}, n = 2}
entries(OrderedMap {{b = 1}, {a = 2}})
elems (om)
Iterate over the keys and values of a map, in order. Don't add or remove keys while iterating.

Parameters:

  • om OrderedMap a map

Returns:

  1. function an iterator that returns a key and its value
  2. OrderedMap om

Usage:

    for key, value in elems(om) do print(key, value) end
get (om, key)
The value of a key.

Parameters:

  • om OrderedMap a map
  • key a key

Returns:

    the value of key, or nil

Usage:

    local value = get(om, 'key')
keys (om)
The keys of a map, in order.

Parameters:

  • om OrderedMap a map

Returns:

    table the keys in order, with their number in field n

Usage:

    --> {'b', 'a', n = 2}
keys(OrderedMap {{b = 1}, {a = 2}})
merged (...)
Make a new map of the entries of the maps given. Keys are in the order they first appear, and a key that is in more than one map keeps its first place and the value of the last.

Parameters:

  • ... OrderedMap maps to merge, where nil is skipped

Returns:

    OrderedMap a new map

Usage:

    --> OrderedMap {a=3, b=2, c=4}
merged(OrderedMap {{a = 1}, {b = 2}}, OrderedMap {{c = 4}, {a = 3}})
mapvalues (om, fn)
Make a new map of the values of a map, with a function applied. Keys keep their order, and a key whose function result is nil is left out.

Parameters:

  • om OrderedMap a map
  • fn callable called with a value and then its key

Returns:

    OrderedMap a new map

Usage:

    --> OrderedMap {a=10, b=20}
mapvalues(OrderedMap {{a = 1}, {b = 2}}, function(v) return v * 10 end)
pluck (om, keylist)
Make a new map of just some of the entries of a map. The entries are in the order of the map, and not of the keys.

Parameters:

  • om OrderedMap a map
  • keylist table the keys to keep

Returns:

    OrderedMap a new map

Usage:

    --> OrderedMap {a=1, c=3}
pluck(OrderedMap {{a = 1}, {b = 2}, {c = 3}}, {'c', 'a'})
set (om, key, value)
Set the value of a key, or remove it with nil. A new key goes to the end of the map.

Parameters:

  • om OrderedMap a map
  • key a key
  • value the new value, or nil to remove key

Returns:

    OrderedMap om

Usage:

    set(om, 'key', 'value')
size (om)
The number of keys in a map. Not its length, which is that of the sequence part of its fields: the keys are counted every time, so keep the result if you want it again.

Parameters:

  • om OrderedMap a map

Returns:

    int the number of keys

Usage:

    --> 2
size(OrderedMap {{b = 1}, {a = 2}})
values (om)
The values of a map, in the order of its keys.

Parameters:

  • om OrderedMap a map

Returns:

    table the values in order, with their number in field n

Usage:

    --> {1, 2, n = 2}
values(OrderedMap {{b = 1}, {a = 2}})
generated by LDoc 1.5.0 Last updated 2026-10-28 10:28:35