class std.HashTable

Overview

This class provides a hash-table-based mapping from variant_t-s to variant_t-s. More…

import "std_HashTable.jnc"

class HashTable {
    // fields

    std.MapEntry cmut* readonly m_head;
    std.MapEntry cmut* readonly m_tail;
    size_t readonly m_count;

    // properties

    bool const property m_isEmpty;

    // construction

    construct(
        std.HashFunc thin* hashFunc = null,
        std.IsEqualFunc thin* isEqualFunc = null
    );
    destruct();

    // methods

    void clear();
    std.MapEntry* errorcode visit(variant_t key);
    std.MapEntry cmut* find(variant_t key) const;

    variant_t findValue(
        variant_t key,
        variant_t undefinedValue = null
    ) const;

    std.MapEntry* errorcode add(
        variant_t key,
        variant_t value
    );

    void remove(std.MapEntry* entry);
    bool removeKey(variant_t key);
};

Detailed Documentation

This class provides a hash-table-based mapping from variant_t-s to variant_t-s.

std.HashTable stores (key; value) pairs and provides fast lookup of the value associated with a key.

A typical sequence of steps when working with a hash table usually looks like this:

• Add (key; value) pairs using add method(or by accessing the indexer property);

• Remove (key; value) pairs using remove or removeKey methods;

• Find value associated with a key using find, findValue method(or by accessing the indexer property).

Sample code:

enum State {
    Idle,
    Running,
    Stopping,
    _Count
}

std.HashTable hashTable;

hashTable[State.Idle] = "idle";
hashTable[State.Running] = "running";
hashTable[State.Stopping] = "stopping";

State state = (State)(rand() % State._Count);

printf($"state: $(hashTable [state])\n");

Properties

bool const property m_isEmpty

Returns true if hash table is empty; false otherwise.

Methods

void clear()

Remove all entries from the hash table.

std.MapEntry cmut* find(variant_t key) const

Looks up a value associated with the key key.

If the value is found, it is copied to the buffer pointed to by value; then find method returns true.

Returns false if key key is not found.

variant_t findValue(
    variant_t key,
    variant_t undefinedValue = null
) const

Looks up a value associated with the key key.

Returns the found value or undefinedValue if the value is not found.

undefinedValue must be chosen distinct from all the possible values in the hash table so it can be used as a key-not-found token.

std.MapEntry* errorcode add(
    variant_t key,
    variant_t value
)

Adds a new (key; value) pair into the hash table.

If key is already in the hash, insert re-writes the value of existing association with the new value specified by the value argument.

bool removeKey(variant_t key)

Finds and deletes key from the hash table.

Returns true if key was found and (key; value) pair successfully deleted.

Returns false if key was not found.