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 tString tables can be created from a table constructor:
Example:
import std/strtabs var t = {"name": "John", "city": "Monaco"}.newStringTableWhen 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
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 counter: int data: KeyValuePairSeq mode: StringTableMode
- Source Edit
Procs
proc `$`(t: StringTableRef): string {....gcsafe, extern: "nstDollar", raises: [], tags: [].}
- 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].}
-
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, val: string) {....gcsafe, extern: "nstPut", raises: [], tags: [].}
-
Inserts a (key, value) pair into t.
See also:
Example:
var t = {"name": "John", "city": "Monaco"}.newStringTable t["occupation"] = "teacher" doAssert t.hasKey("occupation")
Source Edit proc `[]`(t: StringTableRef; key: string): var string {....gcsafe, extern: "nstTake", raises: [KeyError], tags: [].}
-
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 clear(s: StringTableRef) {....raises: [], tags: [].}
- 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: [].}
-
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: [].}
-
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: [].}
-
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: [].}
-
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: [].}
-
Returns true if key is in the table t.
See also:
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: [].}
- Returns the number of keys in t. Source Edit
proc mode(t: StringTableRef): StringTableMode {.inline, ...raises: [], tags: [].}
- Source Edit
proc newStringTable(keyValuePairs: varargs[string]; mode: StringTableMode): owned( StringTableRef) {....gcsafe, extern: "nst$1WithPairs", noSideEffect, ...raises: [], tags: [].}
-
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: [].}
-
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: [].}
-
Creates a new empty string table.
See also:
Source Edit
Iterators
iterator keys(t: StringTableRef): string {....raises: [], tags: [].}
- Iterates over every key in the table t. Source Edit
iterator pairs(t: StringTableRef): tuple[key, value: string] {....raises: [], tags: [].}
- Iterates over every (key, value) pair in the table t. Source Edit
iterator values(t: StringTableRef): string {....raises: [], tags: [].}
- Iterates over every value in the table t. Source Edit