# hashes

Dark Mode

- Manual
- Standard library
- Index

Search:
Group by:

This module implements efficient computations of hash values for diverse Nim types. All the procs are based on these two building blocks:

- !& proc used to start or mix a hash value, and
- !$ proc used to finish the hash value.

If you want to implement hash procs for your custom types, you will end up writing the following kind of skeleton of code:

    proc hash(x: Something): Hash =
      ## Computes a Hash from `x`.
      var h: Hash = 0
      # Iterate over parts of `x`.
      for xAtom in x:
        # Mix the atom with the partial hash.
        h = h !& xAtom
      # Finish the hash.
      result = !$h

If your custom types contain fields for which there already is a hash proc, like for example objects made up of `strings`, you can simply hash together the hash value of the individual fields:

    proc hash(x: Something): Hash =
      ## Computes a Hash from `x`.
      var h: Hash = 0
      h = h !& hash(x.foo)
      h = h !& hash(x.bar)
      result = !$h

See also:

- md5 module for MD5 checksum algorithm
- base64 module for a base64 encoder and decoder
- std/sha1 module for a sha1 encoder and decoder
- tables module for hash tables

# Types

    Hash = int

  A hash value. Hash tables using these values should always have a size of a power of two and can use the `and` operator instead of `mod` for truncation of the hash value. Source Edit

# Procs

    proc `!&`(h: Hash; val: int): Hash {...}{.inline, raises: [], tags: [].}

  Mixes a hash value `h` with `val` to produce a new hash value.

  This is only needed if you need to implement a hash proc for a new datatype.

  Source Edit

    proc `!$`(h: Hash): Hash {...}{.inline, raises: [], tags: [].}

  Finishes the computation of the hash value.

  This is only needed if you need to implement a hash proc for a new datatype.

  Source Edit

    proc hashData(data: pointer; size: int): Hash {...}{.raises: [], tags: [].}

  Hashes an array of bytes of size `size`. Source Edit

    proc hash(x: pointer): Hash {...}{.inline, raises: [], tags: [].}

  Efficient hashing of pointers. Source Edit

    proc hash[T: proc](x: T): Hash {...}{.inline.}

  Efficient hashing of proc vars. Closures are supported too. Source Edit

    proc hash[T: Ordinal](x: T): Hash {...}{.inline.}

  Efficient hashing of integers. Source Edit

    proc hash(x: float): Hash {...}{.inline, raises: [], tags: [].}

  Efficient hashing of floats. Source Edit

    proc hash(x: string): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of strings.

  See also:

  - hashIgnoreStyle
  - hashIgnoreCase

  Examples:

      doAssert hash("abracadabra") != hash("AbracadabrA")

  Source Edit

    proc hash(x: cstring): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of null-terminated strings.

  Examples:

      doAssert hash(cstring"abracadabra") == hash("abracadabra")
      doAssert hash(cstring"AbracadabrA") == hash("AbracadabrA")
      doAssert hash(cstring"abracadabra") != hash(cstring"AbracadabrA")

  Source Edit

    proc hash(sBuf: string; sPos, ePos: int): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of a string buffer, from starting position `sPos` to ending position `ePos` (included).

  `hash(myStr, 0, myStr.high)` is equivalent to `hash(myStr)`.

  Examples:

      var a = "abracadabra"
      doAssert hash(a, 0, 3) == hash(a, 7, 10)

  Source Edit

    proc hashIgnoreStyle(x: string): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of strings; style is ignored.

  Note: This uses different hashing algorithm than `hash(string)`.

  See also:

  - hashIgnoreCase

  Examples:

      doAssert hashIgnoreStyle("aBr_aCa_dAB_ra") == hashIgnoreStyle("abracadabra")
      doAssert hashIgnoreStyle("abcdefghi") != hash("abcdefghi")

  Source Edit

    proc hashIgnoreStyle(sBuf: string; sPos, ePos: int): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of a string buffer, from starting position `sPos` to ending position `ePos` (included); style is ignored.

  Note: This uses different hashing algorithm than `hash(string)`.

  `hashIgnoreStyle(myBuf, 0, myBuf.high)` is equivalent to `hashIgnoreStyle(myBuf)`.

  Examples:

      var a = "ABracada_b_r_a"
      doAssert hashIgnoreStyle(a, 0, 3) == hashIgnoreStyle(a, 7, a.high)

  Source Edit

    proc hashIgnoreCase(x: string): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of strings; case is ignored.

  Note: This uses different hashing algorithm than `hash(string)`.

  See also:

  - hashIgnoreStyle

  Examples:

      doAssert hashIgnoreCase("ABRAcaDABRA") == hashIgnoreCase("abRACAdabra")
      doAssert hashIgnoreCase("abcdefghi") != hash("abcdefghi")

  Source Edit

    proc hashIgnoreCase(sBuf: string; sPos, ePos: int): Hash {...}{.raises: [], tags: [].}

  Efficient hashing of a string buffer, from starting position `sPos` to ending position `ePos` (included); case is ignored.

  Note: This uses different hashing algorithm than `hash(string)`.

  `hashIgnoreCase(myBuf, 0, myBuf.high)` is equivalent to `hashIgnoreCase(myBuf)`.

  Examples:

      var a = "ABracadabRA"
      doAssert hashIgnoreCase(a, 0, 3) == hashIgnoreCase(a, 7, 10)

  Source Edit

    proc hash[T: tuple](x: T): Hash

  Efficient hashing of tuples. Source Edit

    proc hash[A](x: openArray[A]): Hash

  Efficient hashing of arrays and sequences. Source Edit

    proc hash[A](aBuf: openArray[A]; sPos, ePos: int): Hash

  Efficient hashing of portions of arrays and sequences, from starting position `sPos` to ending position `ePos` (included).

  `hash(myBuf, 0, myBuf.high)` is equivalent to `hash(myBuf)`.

  Examples:

      let a = [1, 2, 5, 1, 2, 6]
      doAssert hash(a, 0, 1) == hash(a, 3, 4)

  Source Edit

    proc hash[A](x: set[A]): Hash

  Efficient hashing of sets. Source Edit