# ropes

Dark Mode

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs

Search:

This module contains support for a rope data type. Ropes can represent very long strings efficiently; especially concatenation is done in O(1) instead of O(n). They are essentially concatenation trees that are only flattened when converting to a native Nim string. The empty string is represented by `nil`. Ropes are immutable and subtrees can be shared without copying. Leaves can be cached for better memory efficiency at the cost of runtime efficiency.

# Imports

streams

# Types

    Rope = ref RopeObj

  empty rope is represented by nil Source Edit

# Procs

    proc len(a: Rope): int {...}{.gcsafe, extern: "nro$1", raises: [], tags: [].}

  The rope's length. Source Edit

    proc rope(s: string = ""): Rope {...}{.gcsafe, extern: "nro$1Str", raises: [],
                                      tags: [].}

  Converts a string to a rope.

  Example:

      var r = rope("I'm a rope")
      doAssert $r == "I'm a rope"

  Source Edit

    proc rope(i: BiggestInt): Rope {...}{.gcsafe, extern: "nro$1BiggestInt", raises: [],
                                     tags: [].}

  Converts an int to a rope.

  Example:

      var r = rope(429)
      doAssert $r == "429"

  Source Edit

    proc rope(f: BiggestFloat): Rope {...}{.gcsafe, extern: "nro$1BiggestFloat",
                                       raises: [], tags: [].}

  Converts a float to a rope.

  Example:

      var r = rope(4.29)
      doAssert $r == "4.29"

  Source Edit

    proc enableCache() {...}{.gcsafe, extern: "nro$1", raises: [], tags: [].}

  Enables the caching of leaves. This reduces the memory footprint at the cost of runtime efficiency. Source Edit

    proc disableCache() {...}{.gcsafe, extern: "nro$1", raises: [], tags: [].}

  The cache is discarded and disabled. The GC will reuse its used memory. Source Edit

    proc `&`(a, b: Rope): Rope {...}{.gcsafe, extern: "nroConcRopeRope", raises: [],
                                 tags: [].}

  The concatenation operator for ropes.

  Example:

      var
        r1 = rope("Hello, ")
        r2 = rope("Nim!")

      let r = r1 & r2
      doAssert $r == "Hello, Nim!"

  Source Edit

    proc `&`(a: Rope; b: string): Rope {...}{.gcsafe, extern: "nroConcRopeStr",
                                         raises: [], tags: [].}

  The concatenation operator for ropes.

  Example:

      var
        r1 = rope("Hello, ")
        r2 = "Nim!"

      let r = r1 & r2
      doAssert $r == "Hello, Nim!"

  Source Edit

    proc `&`(a: string; b: Rope): Rope {...}{.gcsafe, extern: "nroConcStrRope",
                                         raises: [], tags: [].}

  The concatenation operator for ropes.

  Example:

      var
        r1 = "Hello, "
        r2 = rope("Nim!")

      let r = r1 & r2
      doAssert $r == "Hello, Nim!"

  Source Edit

    proc `&`(a: openArray[Rope]): Rope {...}{.gcsafe, extern: "nroConcOpenArray",
                                         raises: [], tags: [].}

  The concatenation operator for an openarray of ropes.

  Example:

      let s = @[rope("Hello, "), rope("Nim"), rope("!")]
      let r = &s
      doAssert $r == "Hello, Nim!"

  Source Edit

    proc add(a: var Rope; b: Rope) {...}{.gcsafe, extern: "nro$1Rope", raises: [],
                                     tags: [].}

  Adds `b` to the rope `a`.

  Example:

      var
        r1 = rope("Hello, ")
        r2 = rope("Nim!")

      r1.add(r2)
      doAssert $r1 == "Hello, Nim!"

  Source Edit

    proc add(a: var Rope; b: string) {...}{.gcsafe, extern: "nro$1Str", raises: [],
                                       tags: [].}

  Adds `b` to the rope `a`.

  Example:

      var
        r1 = rope("Hello, ")
        r2 = "Nim!"

      r1.add(r2)
      doAssert $r1 == "Hello, Nim!"

  Source Edit

    proc `[]`(r: Rope; i: int): char {...}{.gcsafe, extern: "nroCharAt", raises: [],
                                       tags: [].}

  Returns the character at position `i` in the rope `r`. This is quite expensive! Worst-case: O(n). If `i >= r.len`, `\0` is returned.

  Example:

      let r1 = rope("Hello, Nim!")

      doAssert r1[0] == 'H'
      doAssert r1[7] == 'N'
      doAssert r1[22] == '\0'

      let r2 = rope("Hello") & rope(", Nim!")

      doAssert r2[0] == 'H'
      doAssert r2[7] == 'N'
      doAssert r2[22] == '\0'

  Source Edit

    proc write(f: File; r: Rope) {...}{.gcsafe, extern: "nro$1", raises: [IOError],
                                   tags: [WriteIOEffect].}

  Writes a rope to a file. Source Edit

    proc write(s: Stream; r: Rope) {...}{.gcsafe, extern: "nroWriteStream",
                                     raises: [IOError, OSError],
                                     tags: [WriteIOEffect].}

  Writes a rope to a stream. Source Edit

    proc `$`(r: Rope): string {...}{.gcsafe, extern: "nroToString", raises: [], tags: [].}

  Converts a rope back to a string. Source Edit

    proc `%`(frmt: string; args: openArray[Rope]): Rope {...}{.gcsafe,
        extern: "nroFormat", raises: [ValueError], tags: [].}

  `%` substitution operator for ropes. Does not support the `$identifier` nor `${identifier}` notations.

  Example:

      let r1 = "$1 $2 $3" % [rope("Nim"), rope("is"), rope("a great language")]
      doAssert $r1 == "Nim is a great language"

      let r2 = "$# $# $#" % [rope("Nim"), rope("is"), rope("a great language")]
      doAssert $r2 == "Nim is a great language"

  Source Edit

    proc addf(c: var Rope; frmt: string; args: openArray[Rope]) {...}{.gcsafe,
        extern: "nro$1", raises: [ValueError], tags: [].}

  Shortcut for `add(c, frmt % args)`.

  Example:

      var r = rope("Dash: ")
      r.addf "$1 $2 $3", [rope("Nim"), rope("is"), rope("a great language")]
      doAssert $r == "Dash: Nim is a great language"

  Source Edit

    proc equalsFile(r: Rope; f: File): bool {...}{.gcsafe, extern: "nro$1File",
        raises: [IOError], tags: [ReadIOEffect].}

  Returns true if the contents of the file `f` equal `r`. Source Edit

    proc equalsFile(r: Rope; filename: string): bool {...}{.gcsafe, extern: "nro$1Str",
        raises: [IOError], tags: [ReadIOEffect].}

  Returns true if the contents of the file `f` equal `r`. If `f` does not exist, false is returned. Source Edit

# Iterators

    iterator leaves(r: Rope): string {...}{.raises: [], tags: [].}

  Iterates over any leaf string in the rope `r`.

  Example:

      let r = rope("Hello") & rope(", Nim!")
      let s = ["Hello", ", Nim!"]
      var index = 0
      for leave in r.leaves:
        doAssert leave == s[index]
        inc index

  Source Edit

    iterator items(r: Rope): char {...}{.raises: [], tags: [].}

  Iterates over any character in the rope `r`. Source Edit