src/fusion/btreetables

    Dark Mode
Search:
Group by:

Types

Table[A; B] = object
  root: Node[A, B]
  entries: int

Generic sorted table, consisting of key-value pairs.

root and entries are internal implementation details which cannot be directly accessed.

For creating an empty Table, use initTable proc.

TableRef[A; B] = ref Table[A, B]

Ref version of Table.

For creating a new empty TableRef, use newTable proc.

OrderedTable[A; B] = object
  data: seq[(A, B)]
  byKey: Table[A, int]

Table that remembers insertion order.

For creating an empty OrderedTable, use initOrderedTable proc.

OrderedTableRef[A; B] = ref OrderedTable[A, B]

Ref version of OrderedTable.

For creating a new empty OrderedTableRef, use newOrderedTable proc.

CountTable[A] = object
  data: Table[A, int]

Table that counts the number of each key.

For creating an empty CountTable, use initCountTable proc.

CountTableRef[A] = ref CountTable[A]

Ref version of CountTable.

For creating a new empty CountTableRef, use newCountTable proc.

Procs

proc initTable[A, B](initialSize = 0): Table[A, B]

Creates a new empty Table.

The initialSize parameter is there to be compatible with the hash table API, it has no effect on BTree tables.

See also:

Example:

let
  a = initTable[int, string]()
  b = initTable[char, seq[int]]()
proc toTable[A, B](pairs: openArray[(A, B)]): Table[A, B]

Creates a new Table which contains the given pairs.

pairs is a container consisting of (key, value) tuples.

See also:

Example:

let a = [('a', 5), ('b', 9)]
let b = toTable(a)
assert b == {'a': 5, 'b': 9}.toTable
proc getOrDefault[A, B](t: Table[A, B]; x: A): B

Retrieves the value at t[key] if key is in t. Otherwise, the default initialization value for type B is returned (e.g. 0 for any integer type).

See also:

Example:

let a = {'a': 5, 'b': 9}.toTable
doAssert a.getOrDefault('a') == 5
doAssert a.getOrDefault('z') == 0
proc getOrDefault[A, B](t: Table[A, B]; x: A; default: B): B

Retrieves the value at t[key] if key is in t. Otherwise, default is returned.

See also:

Example:

let a = {'a': 5, 'b': 9}.toTable
doAssert a.getOrDefault('a', 99) == 5
doAssert a.getOrDefault('z', 99) == 99
proc `[]`[A, B](t: Table[A, B]; x: A): B

Retrieves the value at t[key].

If key is not in t, the KeyError exception is raised. One can check with hasKey proc whether the key exists.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table

Example:

let a = {'a': 5, 'b': 9}.toTable
doAssert a['a'] == 5
doAssertRaises(KeyError):
  echo a['z']
proc `[]`[A, B](t: var Table[A, B]; x: A): var B

Retrieves the value at t[key]. The value can be modified.

If key is not in t, the KeyError exception is raised.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table
proc hasKey[A, B](t: Table[A, B]; x: A): bool

Returns true if key is in the table t.

See also:

proc contains[A, B](t: Table[A, B]; x: A): bool
Alias of hasKey proc for use with the in operator.

Example:

let a = {'a': 5, 'b': 9}.toTable
doAssert 'b' in a == true
doAssert a.contains('z') == false
proc `[]=`[A, B](t: var Table[A, B]; key: A; val: B)

Inserts a (key, value) pair into t.

See also:

Example:

var a = initTable[char, int]()
a['x'] = 7
a['y'] = 33
doAssert a == {'x': 7, 'y': 33}.toTable
proc hasKeyOrPut[A, B](t: var Table[A, B]; key: A; val: B): bool

Returns true if key is in the table, otherwise inserts value.

See also:

Example:

var a = {'a': 5, 'b': 9}.toTable
if a.hasKeyOrPut('a', 50):
  a['a'] = 99
if a.hasKeyOrPut('z', 50):
  a['z'] = 99
doAssert a == {'a': 99, 'b': 9, 'z': 50}.toTable
proc mgetOrPut[A, B](t: var Table[A, B]; key: A; val: B): var B

Retrieves value at t[key] or puts val if not present, either way returning a value which can be modified.

See also:

Example:

var a = {'a': 5, 'b': 9}.toTable
doAssert a.mgetOrPut('a', 99) == 5
doAssert a.mgetOrPut('z', 99) == 99
doAssert a == {'a': 5, 'b': 9, 'z': 99}.toTable
proc del[A, B](t: var Table[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toTable
a.del('a')
doAssert a == {'b': 9, 'c': 13}.toTable
a.del('z')
doAssert a == {'b': 9, 'c': 13}.toTable
proc pop[A, B](t: var Table[A, B]; key: A; val: var B): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

See also:

Example:

var
  a = {'a': 5, 'b': 9, 'c': 13}.toTable
  i: int
doAssert a.pop('b', i) == true
doAssert a == {'a': 5, 'c': 13}.toTable
doAssert i == 9
i = 0
doAssert a.pop('z', i) == false
doAssert a == {'a': 5, 'c': 13}.toTable
doAssert i == 0
proc take[A, B](t: var Table[A, B]; key: A; val: var B): bool
Alias for:
proc clear[A, B](t: var Table[A, B])

Resets the table so that it is empty.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toTable
doAssert len(a) == 3
clear(a)
doAssert len(a) == 0
proc len[A, B](t: Table[A, B]): int {...}{.inline.}
Returns the number of keys in t.

Example:

let a = {'a': 5, 'b': 9}.toTable
doAssert len(a) == 2
proc `$`[A, B](t: Table[A, B]): string
The $ operator for tables. Used internally when calling echo on a table.
proc `==`[A, B](a, b: Table[A, B]): bool

The == operator for Tables.

Returns true if the content of both tables contains the same key-value pairs. Insert order does not matter.

Example:

let
  a = {'a': 5, 'b': 9, 'c': 13}.toTable
  b = {'b': 9, 'c': 13, 'a': 5}.toTable
doAssert a == b
proc newTable[A, B](): TableRef[A, B]

Creates a new ref table that is empty.

initialSize must be a power of two (default: 64). If you need to accept runtime values for this you could use the nextPowerOfTwo proc from the math module or the rightSize proc from this module.

See also:

Example:

let
  a = newTable[int, string]()
  b = newTable[char, seq[int]]()
proc newTable[A, B](pairs: openArray[(A, B)]): TableRef[A, B]

Creates a new ref table that contains the given pairs.

pairs is a container consisting of (key, value) tuples.

See also:

Example:

let a = [('a', 5), ('b', 9)]
let b = newTable(a)
assert b == {'a': 5, 'b': 9}.newTable
proc newTableFrom[A, B, C](collection: A; index: proc (x: B): C): TableRef[C, B]
Index the collection with the proc provided.
proc `[]`[A, B](t: TableRef[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 proc whether the key exists.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert a['a'] == 5
doAssertRaises(KeyError):
  echo a['z']
proc `[]=`[A, B](t: TableRef[A, B]; key: A; val: B)

Inserts a (key, value) pair into t.

See also:

Example:

var a = newTable[char, int]()
a['x'] = 7
a['y'] = 33
doAssert a == {'x': 7, 'y': 33}.newTable
proc hasKey[A, B](t: TableRef[A, B]; key: A): bool

Returns true if key is in the table t.

See also:

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert a.hasKey('a') == true
doAssert a.hasKey('z') == false
proc contains[A, B](t: TableRef[A, B]; key: A): bool
Alias of hasKey proc for use with the in operator.

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert 'b' in a == true
doAssert a.contains('z') == false
proc hasKeyOrPut[A, B](t: var TableRef[A, B]; key: A; val: B): bool

Returns true if key is in the table, otherwise inserts value.

See also:

Example:

var a = {'a': 5, 'b': 9}.newTable
if a.hasKeyOrPut('a', 50):
  a['a'] = 99
if a.hasKeyOrPut('z', 50):
  a['z'] = 99
doAssert a == {'a': 99, 'b': 9, 'z': 50}.newTable
proc getOrDefault[A, B](t: TableRef[A, B]; key: A): B

Retrieves the value at t[key] if key is in t. Otherwise, the default initialization value for type B is returned (e.g. 0 for any integer type).

See also:

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert a.getOrDefault('a') == 5
doAssert a.getOrDefault('z') == 0
proc getOrDefault[A, B](t: TableRef[A, B]; key: A; default: B): B

Retrieves the value at t[key] if key is in t. Otherwise, default is returned.

See also:

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert a.getOrDefault('a', 99) == 5
doAssert a.getOrDefault('z', 99) == 99
proc mgetOrPut[A, B](t: TableRef[A, B]; key: A; val: B): var B

Retrieves value at t[key] or puts val if not present, either way returning a value which can be modified.

See also:

Example:

var a = {'a': 5, 'b': 9}.newTable
doAssert a.mgetOrPut('a', 99) == 5
doAssert a.mgetOrPut('z', 99) == 99
doAssert a == {'a': 5, 'b': 9, 'z': 99}.newTable
proc len[A, B](t: TableRef[A, B]): int
Returns the number of keys in t.

Example:

let a = {'a': 5, 'b': 9}.newTable
doAssert len(a) == 2
proc del[A, B](t: TableRef[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

If duplicate keys were added, this may need to be called multiple times.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.newTable
a.del('a')
doAssert a == {'b': 9, 'c': 13}.newTable
a.del('z')
doAssert a == {'b': 9, 'c': 13}.newTable
proc pop[A, B](t: TableRef[A, B]; key: A; val: var B): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

If duplicate keys were added, this may need to be called multiple times.

See also:

Example:

var
  a = {'a': 5, 'b': 9, 'c': 13}.newTable
  i: int
doAssert a.pop('b', i) == true
doAssert a == {'a': 5, 'c': 13}.newTable
doAssert i == 9
i = 0
doAssert a.pop('z', i) == false
doAssert a == {'a': 5, 'c': 13}.newTable
doAssert i == 0
proc take[A, B](t: TableRef[A, B]; key: A; val: var B): bool {...}{.inline.}
Alias for:
proc clear[A, B](t: TableRef[A, B])

Resets the table so that it is empty.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.newTable
doAssert len(a) == 3
clear(a)
doAssert len(a) == 0
proc `$`[A, B](t: TableRef[A, B]): string
The $ operator for tables. Used internally when calling echo on a table.
proc `==`[A, B](s, t: TableRef[A, B]): bool
The == operator for tables. Returns true if either both tables are nil, or neither is nil and the content of both tables contains the same key-value pairs. Insert order does not matter.

Example:

let
  a = {'a': 5, 'b': 9, 'c': 13}.newTable
  b = {'b': 9, 'c': 13, 'a': 5}.newTable
doAssert a == b
proc initOrderedTable[A, B](initialSize = 64): OrderedTable[A, B]

Creates a new ordered table that is empty.

Starting from Nim v0.20, tables are initialized by default and it is not necessary to call this function explicitly.

See also:

Example:

let
  a = initOrderedTable[int, string]()
  b = initOrderedTable[char, seq[int]]()
proc `[]=`[A, B](t: var OrderedTable[A, B]; k: A; v: B)

Inserts a (key, value) pair into t.

See also:

Example:

var a = initOrderedTable[char, int]()
a['x'] = 7
a['y'] = 33
doAssert a == {'x': 7, 'y': 33}.toOrderedTable
proc toOrderedTable[A, B](pairs: openArray[(A, B)]): OrderedTable[A, B]

Creates a new ordered table that contains the given pairs.

pairs is a container consisting of (key, value) tuples.

See also:

Example:

let a = [('a', 5), ('b', 9)]
let b = toOrderedTable(a)
assert b == {'a': 5, 'b': 9}.toOrderedTable
proc `[]`[A, B](t: OrderedTable[A, B]; key: A): B

Retrieves the value at t[key].

If key is not in t, the KeyError exception is raised. One can check with hasKey proc whether the key exists.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert a['a'] == 5
doAssertRaises(KeyError):
  echo a['z']
proc `[]`[A, B](t: var OrderedTable[A, B]; key: A): var B

Retrieves the value at t[key]. The value can be modified.

If key is not in t, the KeyError exception is raised.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table
proc hasKey[A, B](t: OrderedTable[A, B]; key: A): bool

Returns true if key is in the table t.

See also:

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert a.hasKey('a') == true
doAssert a.hasKey('z') == false
proc contains[A, B](t: OrderedTable[A, B]; key: A): bool
Alias of hasKey proc for use with the in operator.

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert 'b' in a == true
doAssert a.contains('z') == false
proc hasKeyOrPut[A, B](t: var OrderedTable[A, B]; key: A; val: B): bool

Returns true if key is in the table, otherwise inserts value.

See also:

Example:

var a = {'a': 5, 'b': 9}.toOrderedTable
if a.hasKeyOrPut('a', 50):
  a['a'] = 99
if a.hasKeyOrPut('z', 50):
  a['z'] = 99
doAssert a == {'a': 99, 'b': 9, 'z': 50}.toOrderedTable
proc getOrDefault[A, B](t: OrderedTable[A, B]; key: A): B

Retrieves the value at t[key] if key is in t. Otherwise, the default initialization value for type B is returned (e.g. 0 for any integer type).

See also:

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert a.getOrDefault('a') == 5
doAssert a.getOrDefault('z') == 0
proc getOrDefault[A, B](t: OrderedTable[A, B]; key: A; default: B): B

Retrieves the value at t[key] if key is in t. Otherwise, default is returned.

See also:

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert a.getOrDefault('a', 99) == 5
doAssert a.getOrDefault('z', 99) == 99
proc mgetOrPut[A, B](t: var OrderedTable[A, B]; key: A; val: B): var B

Retrieves value at t[key] or puts val if not present, either way returning a value which can be modified.

See also:

Example:

var a = {'a': 5, 'b': 9}.toOrderedTable
doAssert a.mgetOrPut('a', 99) == 5
doAssert a.mgetOrPut('z', 99) == 99
doAssert a == {'a': 5, 'b': 9, 'z': 99}.toOrderedTable
proc len[A, B](t: OrderedTable[A, B]): int {...}{.inline.}
Returns the number of keys in t.

Example:

let a = {'a': 5, 'b': 9}.toOrderedTable
doAssert len(a) == 2
proc add[A, B](t: var OrderedTable[A, B]; key: A; val: B)
proc del[A, B](t: var OrderedTable[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

NOTE: This proc is destructive: the original order of the elements is not preserved!

If you want to keep the order of elements after removal, use delete proc.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toOrderedTable
a.del('a')
doAssert a == {'c': 13, 'b': 9}.toOrderedTable
a.del('z')
doAssert a == {'c': 13, 'b': 9}.toOrderedTable
proc delete[A, B](t: var OrderedTable[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

O(n) complexity.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toOrderedTable
a.delete('a')
doAssert a == {'b': 9, 'c': 13}.toOrderedTable
a.delete('z')
doAssert a == {'b': 9, 'c': 13}.toOrderedTable
proc pop[A, B](t: var OrderedTable[A, B]; key: A; val: var B): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

O(n) complexity.

See also:

Example:

var
  a = {'c': 5, 'b': 9, 'a': 13}.toOrderedTable
  i: int
doAssert a.pop('b', i) == true
doAssert a == {'c': 5, 'a': 13}.toOrderedTable
doAssert i == 9
i = 0
doAssert a.pop('z', i) == false
doAssert a == {'c': 5, 'a': 13}.toOrderedTable
doAssert i == 0
proc clear[A, B](t: var OrderedTable[A, B])

Resets the table so that it is empty.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toOrderedTable
doAssert len(a) == 3
clear(a)
doAssert len(a) == 0
proc `$`[A, B](t: OrderedTable[A, B]): string
The $ operator for ordered tables. Used internally when calling echo on a table.
proc `==`[A, B](s, t: OrderedTable[A, B]): bool
The == operator for ordered tables. Returns true if both the content and the order are equal.

Example:

let
  a = {'a': 5, 'b': 9, 'c': 13}.toOrderedTable
  b = {'b': 9, 'c': 13, 'a': 5}.toOrderedTable
doAssert a != b
proc newOrderedTable[A, B](initialSize = 64): OrderedTableRef[A, B]

Creates a new ordered ref table that is empty.

See also:

Example:

let
  a = newOrderedTable[int, string]()
  b = newOrderedTable[char, seq[int]]()
proc newOrderedTable[A, B](pairs: openArray[(A, B)]): OrderedTableRef[A, B]

Creates a new ordered ref table that contains the given pairs.

pairs is a container consisting of (key, value) tuples.

See also:

Example:

let a = [('a', 5), ('b', 9)]
let b = newOrderedTable(a)
assert b == {'a': 5, 'b': 9}.newOrderedTable
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 proc whether the key exists.

See also:

  • getOrDefault proc to return a default value (e.g. zero for int) if the key doesn't exist
  • getOrDefault proc to return a custom value if the key doesn't exist
  • []= proc for inserting a new (key, value) pair in the table
  • hasKey proc for checking if a key is in the table

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert a['a'] == 5
doAssertRaises(KeyError):
  echo a['z']
proc `[]=`[A, B](t: OrderedTableRef[A, B]; key: A; val: B)

Inserts a (key, value) pair into t.

See also:

Example:

var a = newOrderedTable[char, int]()
a['x'] = 7
a['y'] = 33
doAssert a == {'x': 7, 'y': 33}.newOrderedTable
proc hasKey[A, B](t: OrderedTableRef[A, B]; key: A): bool

Returns true if key is in the table t.

See also:

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert a.hasKey('a') == true
doAssert a.hasKey('z') == false
proc contains[A, B](t: OrderedTableRef[A, B]; key: A): bool
Alias of hasKey proc for use with the in operator.

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert 'b' in a == true
doAssert a.contains('z') == false
proc hasKeyOrPut[A, B](t: var OrderedTableRef[A, B]; key: A; val: B): bool

Returns true if key is in the table, otherwise inserts value.

See also:

Example:

var a = {'a': 5, 'b': 9}.newOrderedTable
if a.hasKeyOrPut('a', 50):
  a['a'] = 99
if a.hasKeyOrPut('z', 50):
  a['z'] = 99
doAssert a == {'a': 99, 'b': 9, 'z': 50}.newOrderedTable
proc getOrDefault[A, B](t: OrderedTableRef[A, B]; key: A): B

Retrieves the value at t[key] if key is in t. Otherwise, the default initialization value for type B is returned (e.g. 0 for any integer type).

See also:

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert a.getOrDefault('a') == 5
doAssert a.getOrDefault('z') == 0
proc getOrDefault[A, B](t: OrderedTableRef[A, B]; key: A; default: B): B

Retrieves the value at t[key] if key is in t. Otherwise, default is returned.

See also:

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert a.getOrDefault('a', 99) == 5
doAssert a.getOrDefault('z', 99) == 99
proc mgetOrPut[A, B](t: OrderedTableRef[A, B]; key: A; val: B): var B

Retrieves value at t[key] or puts val if not present, either way returning a value which can be modified.

See also:

Example:

var a = {'a': 5, 'b': 9}.newOrderedTable
doAssert a.mgetOrPut('a', 99) == 5
doAssert a.mgetOrPut('z', 99) == 99
doAssert a == {'a': 5, 'b': 9, 'z': 99}.newOrderedTable
proc len[A, B](t: OrderedTableRef[A, B]): int {...}{.inline.}
Returns the number of keys in t.

Example:

let a = {'a': 5, 'b': 9}.newOrderedTable
doAssert len(a) == 2
proc del[A, B](t: OrderedTableRef[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

NOTE: This proc is destructive: the original order of the elements is not preserved!

If you want to keep the order of elements after removal, use delete proc.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.newOrderedTable
a.del('a')
doAssert a == {'c': 13, 'b': 9}.newOrderedTable
a.del('z')
doAssert a == {'c': 13, 'b': 9}.newOrderedTable
proc delete[A, B](t: OrderedTableRef[A, B]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

O(n) complexity.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.toOrderedTable
a.delete('a')
doAssert a == {'b': 9, 'c': 13}.toOrderedTable
a.delete('z')
doAssert a == {'b': 9, 'c': 13}.toOrderedTable
proc pop[A, B](t: OrderedTableRef[A, B]; key: A; val: var B): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

See also:

Example:

var
  a = {'c': 5, 'b': 9, 'a': 13}.newOrderedTable
  i: int
doAssert a.pop('b', i) == true
doAssert a == {'c': 5, 'a': 13}.newOrderedTable
doAssert i == 9
i = 0
doAssert a.pop('z', i) == false
doAssert a == {'c': 5, 'a': 13}.newOrderedTable
doAssert i == 0
proc clear[A, B](t: OrderedTableRef[A, B])

Resets the table so that it is empty.

See also:

Example:

var a = {'a': 5, 'b': 9, 'c': 13}.newOrderedTable
doAssert len(a) == 3
clear(a)
doAssert len(a) == 0
proc `$`[A, B](t: OrderedTableRef[A, B]): string
The $ operator for ordered tables. Used internally when calling echo on a table.
proc `==`[A, B](s, t: OrderedTableRef[A, B]): bool
The == operator for ordered tables. Returns true if either both tables are nil, or neither is nil and the content and the order of both are equal.

Example:

let
  a = {'a': 5, 'b': 9, 'c': 13}.newOrderedTable
  b = {'b': 9, 'c': 13, 'a': 5}.newOrderedTable
doAssert a != b
proc initCountTable[A](initialSize = 64): CountTable[A]

Creates a new count table that is empty.

Starting from Nim v0.20, tables are initialized by default and it is not necessary to call this function explicitly.

See also:

proc toCountTable[A](keys: openArray[A]): CountTable[A]
Creates a new count table with every member of a container keys having a count of how many times it occurs in that container.
proc `[]`[A](t: CountTable[A]; key: A): int

Retrieves the value at t[key] if key is in t. Otherwise 0 is returned.

See also:

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

Inserts a (key, value) pair into t.

See also:

  • [] proc for retrieving a value of a key
  • inc proc for incrementing a value of a key
proc inc[A](t: var CountTable[A]; key: A; val: Positive = 1)

Increments t[key] by val (default: 1).

val must be a positive number. If you need to decrement a value, use a regular Table instead.

Example:

var a = toCountTable("aab")
a.inc('a')
a.inc('b', 10)
doAssert a == toCountTable("aaabbbbbbbbbbb")
proc smallest[A](t: CountTable[A]): tuple[key: A, val: int]

Returns the (key, value) pair with the smallest val. Efficiency: O(n)

See also:

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

Returns the (key, value) pair with the largest val. Efficiency: O(n)

See also:

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

Returns true if key is in the table t.

See also:

proc contains[A](t: CountTable[A]; key: A): bool
Alias of hasKey proc for use with the in operator.
proc getOrDefault[A](t: CountTable[A]; key: A; default: int = 0): int

Retrieves the value at t[key] ifkey is in t. Otherwise, the integer value of default is returned.

See also:

  • [] proc for retrieving a value of a key
  • hasKey proc for checking if a key is in the table
proc len[A](t: CountTable[A]): int
Returns the number of keys in t.
proc del[A](t: var CountTable[A]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

O(n) complexity.

See also:

Example:

var a = toCountTable("aabbbccccc")
a.del('b')
assert a == toCountTable("aaccccc")
a.del('b')
assert a == toCountTable("aaccccc")
a.del('c')
assert a == toCountTable("aa")
proc pop[A](t: var CountTable[A]; key: A; val: var int): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

O(n) complexity.

See also:

Example:

var a = toCountTable("aabbbccccc")
var i = 0
assert a.pop('b', i)
assert i == 3
i = 99
assert not a.pop('b', i)
assert i == 99
proc clear[A](t: var CountTable[A])

Resets the table so that it is empty.

See also:

proc merge[A](s: var CountTable[A]; t: CountTable[A])
Merges the second table into the first one (must be declared as var).

Example:

var a = toCountTable("aaabbc")
let b = toCountTable("bcc")
a.merge(b)
doAssert a == toCountTable("aaabbbccc")
proc `$`[A](t: CountTable[A]): string
The $ operator for count tables. Used internally when calling echo on a table.
proc `==`[A](s, t: CountTable[A]): bool
The == operator for count tables. Returns true if both tables contain the same keys with the same count. Insert order does not matter.
proc newCountTable[A](initialSize = 64): CountTableRef[A]

Creates a new ref count table that is empty.

See also:

proc newCountTable[A](keys: openArray[A]): CountTableRef[A]
Creates a new ref count table with every member of a container keys having a count of how many times it occurs in that container.
proc `[]`[A](t: CountTableRef[A]; key: A): int

Retrieves the value at t[key] if key is in t. Otherwise 0 is returned.

See also:

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

Inserts a (key, value) pair into t.

See also:

  • [] proc for retrieving a value of a key
  • inc proc for incrementing a value of a key
proc inc[A](t: CountTableRef[A]; key: A; val = 1)
Increments t[key] by val (default: 1).

Example:

var a = newCountTable("aab")
a.inc('a')
a.inc('b', 10)
doAssert a == newCountTable("aaabbbbbbbbbbb")
proc smallest[A](t: CountTableRef[A]): (A, int)

Returns the (key, value) pair with the smallest val. Efficiency: O(n)

See also:

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

Returns the (key, value) pair with the largest val. Efficiency: O(n)

See also:

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

Returns true if key is in the table t.

See also:

proc contains[A](t: CountTableRef[A]; key: A): bool
Alias of hasKey proc for use with the in operator.
proc getOrDefault[A](t: CountTableRef[A]; key: A; default: int): int

Retrieves the value at t[key] ifkey is in t. Otherwise, the integer value of default is returned.

See also:

  • [] proc for retrieving a value of a key
  • hasKey proc for checking if a key is in the table
proc len[A](t: CountTableRef[A]): int
Returns the number of keys in t.
proc del[A](t: CountTableRef[A]; key: A)

Deletes key from table t. Does nothing if the key does not exist.

O(n) complexity.

See also:

proc pop[A](t: CountTableRef[A]; key: A; val: var int): bool

Deletes the key from the table. Returns true, if the key existed, and sets val to the mapping of the key. Otherwise, returns false, and the val is unchanged.

O(n) complexity.

See also:

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

Resets the table so that it is empty.

See also:

proc merge[A](s, t: CountTableRef[A])
Merges the second table into the first one.

Example:

let
  a = newCountTable("aaabbc")
  b = newCountTable("bcc")
a.merge(b)
doAssert a == newCountTable("aaabbbccc")
proc `$`[A](t: CountTableRef[A]): string
The $ operator for count tables. Used internally when calling echo on a table.
proc `==`[A](s, t: CountTableRef[A]): bool
The == operator for count tables. Returns true if either both tables are nil, or neither is nil and both contain the same keys with the same count. Insert order does not matter.

Iterators

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

Iterates over all the keys in the table t.

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toTable
for k in a.keys:
  a[k].add(99)
doAssert a == {'e': @[2, 4, 6, 8, 99], 'o': @[1, 5, 7, 9, 99]}.toTable
iterator keysFrom[A, B](b: Table[A, B]; fromKey: A): A
Iterates over keys in the table from fromKey to the end.
iterator keysBetween[A, B](b: Table[A, B]; fromKey: A; toKey: A): A
Iterates over keys in the table from fromKey to toKey inclusive.
iterator values[A, B](t: Table[A, B]): B

Iterates over all the values in the table t.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toTable
for v in a.values:
  doAssert v.len == 4
iterator mvalues[A, B](t: var Table[A, B]): var B

Iterates over all the values in the table t. The values can be modified.

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toTable
for v in a.mvalues:
  v.add(99)
doAssert a == {'e': @[2, 4, 6, 8, 99], 'o': @[1, 5, 7, 9, 99]}.toTable
iterator valuesFrom[A, B](b: Table[A, B]; fromKey: A): B
Iterates over the values in the table from the given key to the end.
iterator valuesBetween[A, B](b: Table[A, B]; fromKey: A; toKey: A): B
Iterates over the values in the table from fromKey to toKey inclusive.
iterator pairs[A, B](t: Table[A, B]): (A, B)

Iterates over all (key, value) pairs in the table t.

See also:

Examples:

let a = {
  'o': [1, 5, 7, 9],
  'e': [2, 4, 6, 8]
  }.toTable

for k, v in a.pairs:
  echo "key: ", k
  echo "value: ", v

# key: e
# value: [2, 4, 6, 8]
# key: o
# value: [1, 5, 7, 9]
iterator mpairs[A, B](t: var Table[A, B]): (A, var B)

Iterates over all (key, value) pairs in the table t. The values can be modified.

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toTable
for k, v in a.mpairs:
  v.add(v[0] + 10)
doAssert a == {'e': @[2, 4, 6, 8, 12], 'o': @[1, 5, 7, 9, 11]}.toTable
iterator pairsFrom[A, B](b: Table[A, B]; fromKey: A): tuple[key: A, val: B]
Iterates over (key, value) pairs in the table from the given key to the end.
iterator pairsBetween[A, B](b: Table[A, B]; fromKey: A; toKey: A): tuple[key: A,
    val: B]
Iterates over (key, value) pairs in the table from fromKey to toKey inclusive.
iterator keys[A, B](t: TableRef[A, B]): A

Iterates over any key in the table t.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newTable
for k in a.keys:
  a[k].add(99)
doAssert a == {'e': @[2, 4, 6, 8, 99], 'o': @[1, 5, 7, 9, 99]}.newTable
iterator values[A, B](t: TableRef[A, B]): B

Iterates over any value in the table t.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newTable
for v in a.values:
  doAssert v.len == 4
iterator mvalues[A, B](t: TableRef[A, B]): var B

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

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newTable
for v in a.mvalues:
  v.add(99)
doAssert a == {'e': @[2, 4, 6, 8, 99], 'o': @[1, 5, 7, 9, 99]}.newTable
iterator pairs[A, B](t: TableRef[A, B]): (A, B)

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

See also:

Examples:

let a = {
  'o': [1, 5, 7, 9],
  'e': [2, 4, 6, 8]
  }.newTable

for k, v in a.pairs:
  echo "key: ", k
  echo "value: ", v

# key: e
# value: [2, 4, 6, 8]
# key: o
# value: [1, 5, 7, 9]
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.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newTable
for k, v in a.mpairs:
  v.add(v[0] + 10)
doAssert a == {'e': @[2, 4, 6, 8, 12], 'o': @[1, 5, 7, 9, 11]}.newTable
iterator pairs[A, B](t: OrderedTable[A, B]): (A, B)

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

See also:

Examples:

let a = {
  'o': [1, 5, 7, 9],
  'e': [2, 4, 6, 8]
  }.toOrderedTable

for k, v in a.pairs:
  echo "key: ", k
  echo "value: ", v

# key: o
# value: [1, 5, 7, 9]
# key: e
# value: [2, 4, 6, 8]
iterator mpairs[A, B](t: var OrderedTable[A, B]): (A, var B)

Iterates over any (key, value) pair in the table t (must be declared as var) in insertion order. The values can be modified.

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toOrderedTable
for k, v in a.mpairs:
  v.add(v[0] + 10)
doAssert a == {'o': @[1, 5, 7, 9, 11],
               'e': @[2, 4, 6, 8, 12]}.toOrderedTable
iterator keys[A, B](t: OrderedTable[A, B]): A

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

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toOrderedTable
for k in a.keys:
  a[k].add(99)
doAssert a == {'o': @[1, 5, 7, 9, 99],
               'e': @[2, 4, 6, 8, 99]}.toOrderedTable
iterator values[A, B](t: OrderedTable[A, B]): B

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

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toOrderedTable
for v in a.values:
  doAssert v.len == 4
iterator mvalues[A, B](t: var OrderedTable[A, B]): var B

Iterates over any value in the table t (must be declared as var) in insertion order. The values can be modified.

See also:

Example:

var a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.toOrderedTable
for v in a.mvalues:
  v.add(99)
doAssert a == {'o': @[1, 5, 7, 9, 99],
               'e': @[2, 4, 6, 8, 99]}.toOrderedTable
iterator keys[A, B](t: OrderedTableRef[A, B]): A

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

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newOrderedTable
for k in a.keys:
  a[k].add(99)
doAssert a == {'o': @[1, 5, 7, 9, 99], 'e': @[2, 4, 6, 8,
    99]}.newOrderedTable
iterator values[A, B](t: OrderedTableRef[A, B]): B

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

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newOrderedTable
for v in a.values:
  doAssert v.len == 4
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.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newOrderedTable
for v in a.mvalues:
  v.add(99)
doAssert a == {'o': @[1, 5, 7, 9, 99],
               'e': @[2, 4, 6, 8, 99]}.newOrderedTable
iterator pairs[A, B](t: OrderedTableRef[A, B]): (A, B)

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

See also:

Examples:

let a = {
  'o': [1, 5, 7, 9],
  'e': [2, 4, 6, 8]
  }.newOrderedTable

for k, v in a.pairs:
  echo "key: ", k
  echo "value: ", v

# key: o
# value: [1, 5, 7, 9]
# key: e
# value: [2, 4, 6, 8]
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.

See also:

Example:

let a = {
  'o': @[1, 5, 7, 9],
  'e': @[2, 4, 6, 8]
  }.newOrderedTable
for k, v in a.mpairs:
  v.add(v[0] + 10)
doAssert a == {'o': @[1, 5, 7, 9, 11],
               'e': @[2, 4, 6, 8, 12]}.newOrderedTable
iterator pairs[A](t: CountTable[A]): (A, int)

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

See also:

Examples:

let a = toCountTable("abracadabra")

for k, v in pairs(a):
  echo "key: ", k
  echo "value: ", v

# key: a
# value: 5
# key: b
# value: 2
# key: c
# value: 1
# key: d
# value: 1
# key: r
# value: 2
iterator mpairs[A](t: var CountTable[A]): (A, var int)

Iterates over any (key, value) pair in the table t (must be declared as var). The values can be modified.

See also:

Example:

var a = toCountTable("abracadabra")
for k, v in mpairs(a):
  v = 2
doAssert a == toCountTable("aabbccddrr")
iterator keys[A](t: CountTable[A]): A

Iterates over any key in the table t.

See also:

Example:

var a = toCountTable("abracadabra")
for k in keys(a):
  a[k] = 2
doAssert a == toCountTable("aabbccddrr")
iterator values[A](t: CountTable[A]): int

Iterates over any value in the table t.

See also:

Example:

let a = toCountTable("abracadabra")
for v in values(a):
  assert v < 10
iterator mvalues[A](t: var CountTable[A]): var int

Iterates over any value in the table t (must be declared as var). The values can be modified.

See also:

Example:

var a = toCountTable("abracadabra")
for v in mvalues(a):
  v = 2
doAssert a == toCountTable("aabbccddrr")
iterator keys[A](t: CountTableRef[A]): A

Iterates over any key in the table t.

See also:

Example:

let a = newCountTable("abracadabra")
for k in keys(a):
  a[k] = 2
doAssert a == newCountTable("aabbccddrr")
iterator values[A](t: CountTableRef[A]): int

Iterates over any value in the table t.

See also:

Example:

let a = newCountTable("abracadabra")
for v in values(a):
  assert v < 10
iterator mvalues[A](t: CountTableRef[A]): var int

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

See also:

Example:

var a = newCountTable("abracadabra")
for v in mvalues(a):
  v = 2
doAssert a == newCountTable("aabbccddrr")
iterator pairs[A](t: CountTableRef[A]): (A, int)

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

See also:

Examples:

let a = newCountTable("abracadabra")

for k, v in pairs(a):
  echo "key: ", k
  echo "value: ", v

# key: a
# value: 5
# key: b
# value: 2
# key: c
# value: 1
# key: d
# value: 1
# key: r
# value: 2
iterator mpairs[A](t: CountTableRef[A]): (A, var int)

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

See also:

Example:

let a = newCountTable("abracadabra")
for k, v in mpairs(a):
  v = 2
doAssert a == newCountTable("aabbccddrr")