# Module strtabs

The `strtabs` module implements an efficient hash table that is a mapping from strings to strings. Supports a case-sensitive, case-insensitive and style-insensitive mode. An efficient string substitution operator `%` for the string table is also provided.

# Imports

os, hashes, strutils

# Types

    TStringTableMode = enum
      modeCaseSensitive,          ## the table is case sensitive
      modeCaseInsensitive,        ## the table is case insensitive
      modeStyleInsensitive        ## the table is style insensitive

  describes the tables operation mode

    TStringTable = object of TObject
      counter: int
      data: TKeyValuePairSeq
      mode: TStringTableMode

    PStringTable = ref TStringTable

  use this type to declare string tables

    TFormatFlag = enum
      useEnvironment,             ## use environment variable if the ``$key``
                                  ## is not found in the table
      useEmpty,                   ## use the empty string as a default, thus it
                                  ## won't throw an exception if ``$key`` is not
                                  ## in the table
      useKey                      ## do not replace ``$key`` if it is not found
                                  ## in the table (or in the environment)

  flags for the % operator

# Procs

    proc len(t: PStringTable): int {.rtl, extern: "nst$1", raises: [], tags: [].}

  returns the number of keys in t.

    proc `[]`(t: PStringTable; key: string): string {.rtl, extern: "nstGet",
        raises: [], tags: [].}

  retrieves the value at `t[key]`. If key is not in t, "" is returned and no exception is raised. One can check with `hasKey` whether the key exists.

    proc mget(t: PStringTable; key: string): var string {.rtl, extern: "nstTake",
        raises: [EInvalidKey], tags: [].}

  retrieves the location at `t[key]`. If key is not in t, the `EInvalidKey` exception is raised.

    proc hasKey(t: PStringTable; key: string): bool {.rtl, extern: "nst$1",
        raises: [], tags: [].}

  returns true iff key is in the table t.

    proc `[]=`(t: PStringTable; key, val: string) {.rtl, extern: "nstPut",
        raises: [], tags: [].}

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

    proc newStringTable(mode: TStringTableMode): PStringTable {.rtl,
        extern: "nst$1", raises: [], tags: [].}

  creates a new string table that is empty.

    proc newStringTable(keyValuePairs: varargs[string]; mode: TStringTableMode): PStringTable {.
        rtl, extern: "nst$1WithPairs", raises: [], tags: [].}

  creates a new string table with given key value pairs. Example:

      var mytab = newStringTable("key1", "val1", "key2", "val2",
                                 modeCaseInsensitive)

    proc newStringTable(keyValuePairs: varargs[tuple[key, val: string]];
                        mode: TStringTableMode = modeCaseSensitive): PStringTable {.
        rtl, extern: "nst$1WithTableConstr", raises: [], tags: [].}

  creates a new string table with given key value pairs. Example:

      var mytab = newStringTable({"key1": "val1", "key2": "val2"},
                                 modeCaseInsensitive)

    proc `%`(f: string; t: PStringTable; flags: set[TFormatFlag] = {}): string {.
        rtl, extern: "nstFormat", raises: [EInvalidValue], tags: [FReadEnv].}

  The % operator for string tables.

    proc `$`(t: PStringTable): string {.rtl, extern: "nstDollar", raises: [],
                                        tags: [].}

  The $ operator for string tables.

# Iterators

    iterator pairs(t: PStringTable): tuple[key, value: string] {.raises: [],
        tags: [].}

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

    iterator keys(t: PStringTable): string {.raises: [], tags: [].}

  iterates over every key in the table t.

    iterator values(t: PStringTable): string {.raises: [], tags: [].}

  iterates over every value in the table t.

Generated: 2013-05-21 09:55:10 UTC