LinkedMap

Overview

Map implementation in which iteration order is same as insertion order.

In a regular HashMap (or a plain Lua table), the iteration order is dependent on the hash function and can be quite random. This is sometimes undesireable. In a LinkedMap, the iteration order of entries is the same as the order in which the entries are added to the map.

For example:

> a = HashMap:make("edcba", iter.count(5,1,-1)); print(a)
{a=1, c=3, b=2, e=5, d=4}
> a = LinkedMap:make("edcba", iter.count(5,1,-1)); print(a)
{e=5, d=4, c=3, b=2, a=1}

Note that the iteration order is determined only by the first point when an entry is added. If an entry is subsequently modified, its position in the iteration is unchanged unless it is removed then reinserted.

Summary

`new`	Returns a new empty LinkedList.
`make`	Creates and returns a new Map, containing the mappings supplied.
`get`	Returns the value stored against key, or nil if no no such value exists.
`__eq`	Returns true iff maps.orderedEquals(self, other).
`add`	Adds the key-value pair to this map and returns the previous value stored against key (possibly nil).
`contains`	Returns true if this map contains a mapping (possibly nil) for the given key.
`get`	Returns the value stored against key, or nil if no no such value exists.
`iter`	Returns an iterator over the key-value pairs in this map in the same order in which they were inserted.
`remove`	Removes the entry with key == key from this LinkedMap and returns the value associated with key.
`size`	Returns the number of key-value pairs in this LinkedMap.
`test`	Unit test.
`toString`	Returns a string representation of map.
`addMappings`	Adds mappings to this Map and returns Map to allow chaining.
`cDefaultMap`	The default backing map for this LinkedMap (initially HashMap).
`containsAll`	Returns true iff collection:contains(e) for e in iter(iterable).
`removeAll`	Equivalent to calling set:remove(e) for e in iter(elements).
`valIter`	Equivalent to Map:iter() except that iteration steps return elements in the order val,key instead of key,val.

Detail

`LinkedMap:new(mapImpl)`

Returns a new empty LinkedList.

`Map:make(mappings [, vals])`

Creates and returns a new Map, containing the mappings supplied.

input can be one of several types:

A single Lua table {a=1,b=2,c=3,d=4,e=5}
A single iteration which returns two values per iteration step: iter.zip("abcde",iter.count())
Two iterables which both return one value per iteration step - this is a shorthand for 2.
Any table with an iter method which, when called, returns an iteration satisfying 2.

So, the following are all equivalent:

Map:make{a=1,b=2,c=3,d=4,e=5} 
  == Map:make(iter.zip("abcde",iter.count()))
  == Map:make("abcde",iter.count())
  == Map:make(Map:make{a=1,b=2,c=3,d=4,e=5})

`LinkedMap:get(key)`

Returns the value stored against key, or nil if no no such value exists.

If the value of nil is explicitly stored against key, then get(key) will return nil and contains(key) will return true.

synonym: __call So, m:get("h") == m("h")

`LinkedMap:__eq(other)`

Returns true iff maps.orderedEquals(self, other).

`LinkedMap:add(key, val)`

Adds the key-value pair to this map and returns the previous value stored against key (possibly nil).

If there is already a value stored against key, this function is equivalent to a 'set' operation, and has no effect on the iteration order.

`LinkedMap:contains(key)`

Returns true if this map contains a mapping (possibly nil) for the given key.

`LinkedMap:get(key)`

Returns the value stored against key, or nil if no no such value exists.

If the value of nil is explicitly stored against key, then get(key) will return nil and contains(key) will return true.

synonym: __call So, m:get("h") == m("h")

`LinkedMap:iter()`

Returns an iterator over the key-value pairs in this map in the same order in which they were inserted.

Each step in the iteration returns two values.

`LinkedMap:remove(key)`

Removes the entry with key == key from this LinkedMap and returns the value associated with key.

Example:

> h = LinkedMap:make {a=1,b=2}; print(h:remove("a"))
1
> print(h)
{b=2}

`LinkedMap:size()`

Returns the number of key-value pairs in this LinkedMap.

key-value pairs with a nil value are included in the count.

`LinkedMap:test()`

Unit test.

`maps.toString(map)`

Returns a string representation of map.

Example:

> x = HashMap:make{a=1,b=2,c=3,d=4}
> print(x)
{a=1, d=4, c=3, b=2}

`Map:addMappings(mappings, vals)`

Adds mappings to this Map and returns Map to allow chaining.

input can be one of several types:

A single Lua table {a=1,b=2,c=3,d=4,e=5}
A single iteration which returns two values per iteration step: iter.zip("abcde",iter.count())
Two iterables which both return one value per iteration step - this is a shorthand for 2.
Any table with an iter method which, when called, returns an iteration satisfying 2.

So, the following are all equivalent:

Map:addMappings{a=1,b=2,c=3,d=4,e=5} 
  == Map:addMappings(iter.zip("abcde",iter.count()))
  == Map:addMappings("abcde",iter.count())
  == Map:addMappings(Map:addMappings{a=1,b=2,c=3,d=4,e=5})

`LinkedMap.cDefaultMap`

The default backing map for this LinkedMap (initially HashMap).

`collections.containsAll(collection, elements)`

Returns true iff collection:contains(e) for e in iter(iterable).

`sets.removeAll(set, elements)`

Equivalent to calling set:remove(e) for e in iter(elements).

`Map:valIter()`

Equivalent to Map:iter() except that iteration steps return elements in the order val,key instead of key,val.