# std/ropes

Theme:

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

Search:
Source Edit

This module contains support for a rope data type. Ropes can represent very long strings efficiently; in particular, 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, syncio, formatfloat, assertions

# Types

    Rope {.acyclic.} = ref object

  A rope data type. The empty rope is represented by `nil`. Source Edit

# Procs

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

  Converts a rope back to a string. Source Edit

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

  `%` 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"

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

  Source Edit

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

  The concatenation operator for ropes.

  Example:

      let r = rope("Hello, ") & rope("Nim!")
      doAssert $r == "Hello, Nim!"

  Source Edit

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

  The concatenation operator for an `openArray` of ropes.

  Example:

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

  Source Edit

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

  The concatenation operator for ropes.

  Example:

      let r = rope("Hello, ") & "Nim!"
      doAssert $r == "Hello, Nim!"

  Source Edit

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

  The concatenation operator for ropes.

  Example:

      let r = "Hello, " & rope("Nim!")
      doAssert $r == "Hello, Nim!"

  Source Edit

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

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

  Example:

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

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

  Source Edit

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

  Adds `b` to the rope `a`.

  Example:

      var r = rope("Hello, ")
      r.add(rope("Nim!"))
      doAssert $r == "Hello, Nim!"

  Source Edit

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

  Adds `b` to the rope `a`.

  Example:

      var r = rope("Hello, ")
      r.add("Nim!")
      doAssert $r == "Hello, Nim!"

  Source Edit

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

  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 disableCache() {....gcsafe, extern: "nro$1", raises: [], tags: [], forbids: [].}

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

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

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

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

  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], forbids: [].}

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

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

  The rope's length. Source Edit

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

  Converts a float to a rope.

  Example:

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

  Source Edit

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

  Converts an int to a rope.

  Example:

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

  Source Edit

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

  Converts a string to a rope.

  Example:

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

  Source Edit

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

  Writes a rope to a file. Source Edit

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

  Writes a rope to a stream. Source Edit

# Iterators

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

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

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

  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