Module tables

The tables module implements variants of an efficient hash table (also often named dictionary in other programming languages) that is a mapping from keys to values. Table is the usual hash table, OrderedTable is like Table but remembers insertion order and CountTable is a mapping from a key to its number of occurrences. For consistency with every other data type in Nim these have value semantics, this means that = performs a copy of the hash table. For reference semantics use the Ref variant: TableRef, OrderedTableRef, CountTableRef. To give an example, when a is a Table, then var b = a gives b as a new independent table. b is initialised with the contents of a. Changing b does not affect a and vice versa:

If you are using simple standard types like int or string for the keys of the table you won't have any problems, but as soon as you try to use a more complex object as a key you will be greeted by a strange compiler error:

What is happening here is that the types used for table keys require to have a hash() proc which will convert them to a Hash value, and the compiler is listing all the hash functions it knows. Additionally there has to be a == operator that provides the same semantics as its corresponding hash proc.

After you add hash and == for your custom type everything will work. Currently however hash for objects is not defined, whereas system.== for objects does exist and performs a "deep" comparison (every field is compared) which is usually what you want. So in the following example implementing only hash suffices:

sorts t according to cmp. This modifies the internal list that kept the insertion order, so insertion order is lost after this call but key lookup and insertions remain possible after sort (in contrast to the sort for count tables).

proc len[A, B](t: OrderedTableRef[A, B]): int {.inline.}

returns the number of keys in t.

proc `[]`[A, B](t: OrderedTableRef[A, B]; key: A): var B

retrieves the value at t[key]. If key is not in t, the KeyError exception is raised. One can check with hasKey whether the key exists.

sorts t according to cmp. This modifies the internal list that kept the insertion order, so insertion order is lost after this call but key lookup and insertions remain possible after sort (in contrast to the sort for count tables).

proc del[A, B](t: var OrderedTable[A, B]; key: A)

deletes key from ordered hash table t. O(n) complexity.

proc del[A, B](t: var OrderedTableRef[A, B]; key: A)

deletes key from ordered hash table t. O(n) complexity.

proc len[A](t: CountTable[A]): int

returns the number of keys in t.

proc clear[A](t: CountTableRef[A])

Resets the table so that it is empty.

proc clear[A](t: var CountTable[A])

Resets the table so that it is empty.

proc `[]`[A](t: CountTable[A]; key: A): int {..}

retrieves the value at t[key]. If key is not in t, the KeyError exception is raised. One can check with hasKey whether the key exists.

proc `[]`[A](t: var CountTable[A]; key: A): var int {..}

retrieves the value at t[key]. The value can be modified. If key is not in t, the KeyError exception is raised.

proc mget[A](t: var CountTable[A]; key: A): var int {.deprecated.}

retrieves the value at t[key]. The value can be modified. If key is not in t, the KeyError exception is raised. Use ```[]``` instead.

proc getOrDefault[A](t: CountTable[A]; key: A): int

proc hasKey[A](t: CountTable[A]; key: A): bool

returns true iff key is in the table t.

proc contains[A](t: CountTable[A]; key: A): bool

alias of hasKey for use with the in operator.

proc `[]=`[A](t: var CountTable[A]; key: A; val: int)

puts a (key, value)-pair into t.

proc initCountTable[A](initialSize = 64): CountTable[A]

creates a new count table that is empty.

initialSize needs to be a power of two. If you need to accept runtime values for this you could use the nextPowerOfTwo proc from the math module or the rightSize proc in this module.

proc toCountTable[A](keys: openArray[A]): CountTable[A]

creates a new count table with every key in keys having a count of 1.

proc `$`[A](t: CountTable[A]): string

The $ operator for count tables.

proc `==`[A](s, t: CountTable[A]): bool

The == operator for count tables. Returns true iff both tables contain the same keys with the same count. Insert order does not matter.

proc inc[A](t: var CountTable[A]; key: A; val = 1)

increments t[key] by val.

proc smallest[A](t: CountTable[A]): tuple[key: A, val: int]

returns the (key,val)-pair with the smallest val. Efficiency: O(n)

proc largest[A](t: CountTable[A]): tuple[key: A, val: int]

returns the (key,val)-pair with the largest val. Efficiency: O(n)

proc sort[A](t: var CountTable[A])

sorts the count table so that the entry with the highest counter comes first. This is destructive! You must not modify t afterwards! You can use the iterators pairs, keys, and values to iterate over t in the sorted order.

proc len[A](t: CountTableRef[A]): int

returns the number of keys in t.

proc `[]`[A](t: CountTableRef[A]; key: A): var int {..}

retrieves the value at t[key]. The value can be modified. If key is not in t, the KeyError exception is raised.

proc mget[A](t: CountTableRef[A]; key: A): var int {.deprecated.}

retrieves the value at t[key]. The value can be modified. If key is not in t, the KeyError exception is raised. Use ```[]``` instead.

proc getOrDefault[A](t: CountTableRef[A]; key: A): int

proc hasKey[A](t: CountTableRef[A]; key: A): bool

returns true iff key is in the table t.

proc contains[A](t: CountTableRef[A]; key: A): bool

alias of hasKey for use with the in operator.

proc `[]=`[A](t: CountTableRef[A]; key: A; val: int)

puts a (key, value)-pair into t. val has to be positive.

proc newCountTable[A](initialSize = 64): CountTableRef[A]

creates a new count table that is empty.

initialSize needs to be a power of two. If you need to accept runtime values for this you could use the nextPowerOfTwo proc from the math module or the rightSize method in this module.

proc newCountTable[A](keys: openArray[A]): CountTableRef[A]

creates a new count table with every key in keys having a count of 1.

proc `$`[A](t: CountTableRef[A]): string

The $ operator for count tables.

proc `==`[A](s, t: CountTableRef[A]): bool

The == operator for count tables. Returns true iff either both tables are nil or none is nil and both contain the same keys with the same count. Insert order does not matter.

proc inc[A](t: CountTableRef[A]; key: A; val = 1)

increments t[key] by val.

proc smallest[A](t: CountTableRef[A]): (A, int)

returns the (key,val)-pair with the smallest val. Efficiency: O(n)

proc largest[A](t: CountTableRef[A]): (A, int)

returns the (key,val)-pair with the largest val. Efficiency: O(n)

proc sort[A](t: CountTableRef[A])

sorts the count table so that the entry with the highest counter comes first. This is destructive! You must not modify t afterwards! You can use the iterators pairs, keys, and values to iterate over t in the sorted order.

proc merge[A](s: var CountTable[A]; t: CountTable[A])

merges the second table into the first one

proc merge[A](s, t: CountTable[A]): CountTable[A]

merges the two tables into a new one

proc merge[A](s, t: CountTableRef[A])

merges the second table into the first one

Iterators

iterator allValues[A, B](t: Table[A, B]; key: A): B

iterates over any value in the table t that belongs to the given key.

iterator pairs[A, B](t: Table[A, B]): (A, B)

iterates over any (key, value) pair in the table t.

iterator mpairs[A, B](t: var Table[A, B]): (A, var B)

iterates over any (key, value) pair in the table t. The values can be modified.

iterator keys[A, B](t: Table[A, B]): A

iterates over any key in the table t.

iterator values[A, B](t: Table[A, B]): B

iterates over any value in the table t.

iterator mvalues[A, B](t: var Table[A, B]): var B

iterates over any value in the table t. The values can be modified.

iterator pairs[A, B](t: TableRef[A, B]): (A, B)

iterates over any (key, value) pair in the table t.

iterator mpairs[A, B](t: TableRef[A, B]): (A, var B)

iterates over any (key, value) pair in the table t. The values can be modified.

iterator keys[A, B](t: TableRef[A, B]): A

iterates over any key in the table t.

iterator values[A, B](t: TableRef[A, B]): B

iterates over any value in the table t.

iterator mvalues[A, B](t: TableRef[A, B]): var B

iterates over any value in the table t. The values can be modified.

iterator pairs[A, B](t: OrderedTable[A, B]): (A, B)

iterates over any (key, value) pair in the table t in insertion order.

iterator mpairs[A, B](t: var OrderedTable[A, B]): (A, var B)

iterates over any (key, value) pair in the table t in insertion order. The values can be modified.

iterator keys[A, B](t: OrderedTable[A, B]): A

iterates over any key in the table t in insertion order.

iterator values[A, B](t: OrderedTable[A, B]): B

iterates over any value in the table t in insertion order.

iterator mvalues[A, B](t: var OrderedTable[A, B]): var B

iterates over any value in the table t in insertion order. The values can be modified.

iterator pairs[A, B](t: OrderedTableRef[A, B]): (A, B)

iterates over any (key, value) pair in the table t in insertion order.

iterator mpairs[A, B](t: OrderedTableRef[A, B]): (A, var B)

iterates over any (key, value) pair in the table t in insertion order. The values can be modified.

iterator keys[A, B](t: OrderedTableRef[A, B]): A

iterates over any key in the table t in insertion order.

iterator values[A, B](t: OrderedTableRef[A, B]): B

iterates over any value in the table t in insertion order.

iterator mvalues[A, B](t: OrderedTableRef[A, B]): var B

iterates over any value in the table t in insertion order. The values can be modified.

iterator pairs[A](t: CountTable[A]): (A, int)

iterates over any (key, value) pair in the table t.

iterator mpairs[A](t: var CountTable[A]): (A, var int)

iterates over any (key, value) pair in the table t. The values can be modified.

iterator keys[A](t: CountTable[A]): A

iterates over any key in the table t.

iterator values[A](t: CountTable[A]): int

iterates over any value in the table t.

iterator mvalues[A](t: CountTable[A]): var int

iterates over any value in the table t. The values can be modified.

iterator pairs[A](t: CountTableRef[A]): (A, int)

iterates over any (key, value) pair in the table t.

iterator mpairs[A](t: CountTableRef[A]): (A, var int)

iterates over any (key, value) pair in the table t. The values can be modified.