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:

  1. import std/strtabs
  2. var t = newStringTable()
  3. t["name"] = "John"
  4. t["city"] = "Monaco"
  5. doAssert t.len == 2
  6. doAssert t.hasKey "name"
  7. doAssert "name" in t

String tables can be created from a table constructor:

Example:

  1. import std/strtabs
  2. 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:

  1. import std/strtabs
  2. var x = newStringTable(modeStyleInsensitive)
  3. x["first_name"] = "John"
  4. x["LastName"] = "Doe"
  6. doAssert x["firstName"] == "John"
  7. doAssert x["last_name"] == "Doe"

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

Example:

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

See also:

Imports

since, hashes, strutils, envvars

Types

  1. FormatFlag = enum
  2.   useEnvironment,           ## Use environment variable if the ``$key``
  3.                              ## is not found in the table.
  4.                              ## Does nothing when using `js` target.
  5.   useEmpty,                 ## Use the empty string as a default, thus it
  6.                              ## won't throw an exception if ``$key`` is not
  7.                              ## in the table.
  8.   useKey                     ## Do not replace ``$key`` if it is not found
  9.                              ## in the table (or in the environment).

Flags for the % operator. Source Edit 

  1. StringTableMode = enum
  2.   modeCaseSensitive,        ## the table is case sensitive
  3.   modeCaseInsensitive,      ## the table is case insensitive
  4.   modeStyleInsensitive       ## the table is style insensitive

Describes the tables operation mode. Source Edit 

  1. StringTableObj = object of RootObj

Source Edit 

  1. StringTableRef = ref StringTableObj

Source Edit

Procs

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

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

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

The % operator for string tables.

Example:

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

Source Edit 

  1. proc `[]`(t: StringTableRef; key: string): var string {....gcsafe,
  2.     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:

Example:

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

Source Edit 

  1. proc `[]=`(t: StringTableRef; key, val: string) {....gcsafe, extern: "nstPut",
  2.     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:

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

Source Edit 

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

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

  1. proc clear(s: StringTableRef; mode: StringTableMode) {....gcsafe, extern: "nst$1",
  2.     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:

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

Source Edit 

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

Alias of hasKey proc for use with the in operator.

Example:

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

Source Edit 

  1. 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:

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

Source Edit 

  1. proc getOrDefault(t: StringTableRef; key: string; default: string = ""): string {.
  2.     ...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:

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

Source Edit 

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

Returns true if key is in the table t.

See also:

Example:

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

Source Edit 

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

Returns the number of keys in t. Source Edit 

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

Source Edit 

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

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

StringTableMode must be specified.

Example:

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

Source Edit 

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

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

The default mode is case sensitive.

Example:

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

Source Edit 

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

Creates a new empty string table.

See also:

Source Edit

Iterators

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

Iterates over every key in the table t. Source Edit 

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

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

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

Iterates over every value in the table t. Source Edit