Creates a new hash table that is empty.

Capacity must be a power of two. If you need to accept runtime values for this you could use the nextPowerOfTwo proc

After maximum capacity is reached, inserts and upserts will start returning NotInStash. If you need to grow the capacity, create a new larger table, copy items to it with addAll proc and switch reference(s).

Recommended practice is to reserve enough capacity right at initialisation, because

• StashTable is very space-efficient anyway (especially when using pointers as values)
• addAll takes some time and blocked operations will naturally not be reflected in new table.
• addAll will temporarily need enough memory to hold both old and new table
• Last but not least: all extra capacity will speed up execution by lowering probability of hash collisions

• (i , true) : The item was succesfully inserted to Index i
• (i , false) : The item was not inserted because there was already item with the same key at Index i
• (NotInStash , false) : The item was not inserted because stash was full, i.e. len == Capacity

Examples:

let a = newStashTable[char, int, 1024]()
let (index1, wasinserted1) = a.insert('x', 7)
doAssert wasinserted1
let (index2, wasinserted2) = a.insert('x', 33)
doAssert index2 == index1 and not wasinserted2

• (i , true) : The item was succesfully inserted to Index i
• (i , false) : The item already existed at Index i and it's value was updated to given value
• (NotInStash , false) : The key did not exist but the item could not be inserted because stash was full

Deletes key from stash. Does nothing if the key does not exist.

Note that del must not be called from inside a withValue or withFound block. Instead, write down the key and call del afterwards.

let s = newStashTable[int, char, 4]()
var deletables: seq[int]
s[1] = 'a' ; s[2] = 'b' ; s[3] = 'a'
doAssert s.len == 3
for (key, index) in s.keys:
  s.withFound(key, index):
    if value[] != 'b': deletables.add(key)
for key in deletables: s.del(key)
doAssert s.len == 1

Iterates over all (key , index) pairs in the table stash.

feature: if there are no deletes, iteration order is insertion order.

let a = newStashTable[char, array[4, int], 128]()
a['o'] = [1, 5, 7, 9]
a['e'] = [2, 4, 6, 8]
for (k , index) in a.keys:
  a.withFound(k, index):
    echo "key: ", k
    echo "value: ", value[]
    doAssert (k == 'o' and value[] == [1, 5, 7, 9]) or (k == 'e' and value[] == [2, 4, 6, 8])  

Retrieves pointer to the value as variable value at theindex. thekey must also be given to ensure that the given Index is still holding the putative item.

Item is locked and value can be modified in the scope of withFound call.

On one hand this is faster operation than withValue because there's no need to find the Index, but on other hand there's greater probability that the item was deleted and reinserted to other Index by other thread(s) since the Index was retrieved.

Examples:

type
  Item = tuple[name: char, uid: int]
let stash = newStashTable[int, Item, 8]()
let key = 42
stash[key] = ('a', 555)
let index = stash.findIndex(key)
stash.withFound(key, index):
  value.name = 'u'
  value.uid = 1000
stash.withFound(42, 0.Index):
  doAssert value.name == 'u'

Retrieves pointer to the value as variable value for thekey. Item is locked and value can be modified in the scope of withValue call.

Example:

stashTable.withValue(key):
  # block is executed only if ``key`` in ``stashTable``
  value.name = username
  value.uid = 1000
do:
  # block is executed when ``key`` not in ``stashTable``
  raise newException(KeyError, "Key not found")