# std/strtabs

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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.

Example:

    import std/strtabs
    var t = newStringTable()
    t["name"] = "John"
    t["city"] = "Monaco"
    doAssert t.len == 2
    doAssert t.hasKey "name"
    doAssert "name" in t

String tables can be created from a table constructor:

Example:

    import std/strtabs
    var t = {"name": "John", "city": "Monaco"}.newStringTable

When using the style insensitive mode (`modeStyleInsensitive`), all letters are compared case insensitively within the ASCII range and underscores are ignored.

Example:

    import std/strtabs
    var x = newStringTable(modeStyleInsensitive)
    x["first_name"] = "John"
    x["LastName"] = "Doe"

    doAssert x["firstName"] == "John"
    doAssert x["last_name"] == "Doe"

An efficient string substitution operator % for the string table is also provided.

Example:

    import std/strtabs
    var t = {"name": "John", "city": "Monaco"}.newStringTable
    doAssert "${name} lives in ${city}" % t == "John lives in Monaco"

See also:

- tables module for general hash tables
- sharedtables module for shared hash table support
- strutils module for common string functions
- json module for table-like structure which allows heterogeneous members

# Imports

since, hashes, strutils, envvars

# Types

    FormatFlag = enum
      useEnvironment,           ## Use environment variable if the ``$key``
                                 ## is not found in the table.
                                 ## Does nothing when using `js` target.
      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. Source Edit

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

  Describes the tables operation mode. Source Edit

    StringTableObj = object of RootObj

  Source Edit

    StringTableRef = ref StringTableObj

  Source Edit

# Procs

    proc `$`(t: StringTableRef): string {....gcsafe, extern: "nstDollar", raises: [],
                                          tags: [], forbids: [].}

  The `$` operator for string tables. Used internally when calling `echo` on a table. Source Edit

    proc `%`(f: string; t: StringTableRef; flags: set[FormatFlag] = {}): string {.
        ...gcsafe, extern: "nstFormat", raises: [ValueError], tags: [ReadEnvEffect],
        forbids: [].}

  The `%` operator for string tables.

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      doAssert "${name} lives in ${city}" % t == "John lives in Monaco"

  Source Edit

    proc `[]`(t: StringTableRef; key: string): var string {....gcsafe,
        extern: "nstTake", raises: [KeyError], tags: [], forbids: [].}

  Retrieves the location 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
  - []= proc for inserting a new (key, value) pair in the table
  - hasKey proc for checking if a key is in the table

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      doAssert t["name"] == "John"
      doAssertRaises(KeyError):
        echo t["occupation"]

  Source Edit

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

  Inserts a `(key, value)` pair into `t`.

  See also:

  - [] proc for retrieving a value of a key
  - del proc for removing a key from the table

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      t["occupation"] = "teacher"
      doAssert t.hasKey("occupation")

  Source Edit

    proc clear(s: StringTableRef) {....raises: [], tags: [], forbids: [].}

  Resets a string table to be empty again without changing the mode. Source Edit

    proc clear(s: StringTableRef; mode: StringTableMode) {....gcsafe, extern: "nst$1",
        raises: [], tags: [], forbids: [].}

  Resets a string table to be empty again, perhaps altering the mode.

  See also:

  - del proc for removing a key from the table

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      clear(t, modeCaseSensitive)
      doAssert len(t) == 0
      doAssert "name" notin t
      doAssert "city" notin t

  Source Edit

    proc contains(t: StringTableRef; key: string): bool {....raises: [], tags: [],
        forbids: [].}

  Alias of hasKey proc for use with the `in` operator.

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      doAssert "name" in t
      doAssert "occupation" notin t

  Source Edit

    proc del(t: StringTableRef; key: string) {....raises: [], tags: [], forbids: [].}

  Removes `key` from `t`.

  See also:

  - clear proc for resetting a table to be empty
  - []= proc for inserting a new (key, value) pair in the table

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      t.del("name")
      doAssert len(t) == 1
      doAssert "name" notin t
      doAssert "city" in t

  Source Edit

    proc getOrDefault(t: StringTableRef; key: string; default: string = ""): string {.
        ...raises: [], tags: [], forbids: [].}

  Retrieves the location at `t[key]`.

  If `key` is not in `t`, the default value is returned (if not specified, it is an empty string (`""`)).

  See also:

  - [] proc for retrieving a value of a key
  - hasKey proc for checking if a key is in the table
  - []= proc for inserting a new (key, value) pair in the table

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      doAssert t.getOrDefault("name") == "John"
      doAssert t.getOrDefault("occupation") == ""
      doAssert t.getOrDefault("occupation", "teacher") == "teacher"
      doAssert t.getOrDefault("name", "Paul") == "John"

  Source Edit

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

  Returns true if `key` is in the table `t`.

  See also:

  - getOrDefault proc
  - contains proc

  Example:

      var t = {"name": "John", "city": "Monaco"}.newStringTable
      doAssert t.hasKey("name")
      doAssert not t.hasKey("occupation")

  Source Edit

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

  Returns the number of keys in `t`. Source Edit

    proc mode(t: StringTableRef): StringTableMode {.inline, ...raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc newStringTable(keyValuePairs: varargs[string]; mode: StringTableMode): owned(
        StringTableRef) {....gcsafe, extern: "nst$1WithPairs", noSideEffect,
                          ...raises: [], tags: [], forbids: [].}

  Creates a new string table with given `key, value` string pairs.

  `StringTableMode` must be specified.

  Example:

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

  Source Edit

    proc newStringTable(keyValuePairs: varargs[tuple[key, val: string]];
                        mode: StringTableMode = modeCaseSensitive): owned(
        StringTableRef) {....gcsafe, extern: "nst$1WithTableConstr", noSideEffect,
                          ...raises: [], tags: [], forbids: [].}

  Creates a new string table with given `(key, value)` tuple pairs.

  The default mode is case sensitive.

  Example:

      var
        mytab1 = newStringTable({"key1": "val1", "key2": "val2"}, modeCaseInsensitive)
        mytab2 = newStringTable([("key3", "val3"), ("key4", "val4")])

  Source Edit

    proc newStringTable(mode: StringTableMode): owned(StringTableRef) {....gcsafe,
        extern: "nst$1", noSideEffect, ...raises: [], tags: [], forbids: [].}

  Creates a new empty string table.

  See also:

  - newStringTable(keyValuePairs) proc
  Source Edit

# Iterators

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

  Iterates over every key in the table `t`. Source Edit

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

  Iterates over every `(key, value)` pair in the table `t`. Source Edit

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

  Iterates over every value in the table `t`. Source Edit