pure/ropes

    Dark Mode
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.

Types

Rope {.acyclic.} = ref object
  left, right: Rope
  length: int
  data: string
A rope data type. The empty rope is represented by nil.   Source   Edit

Procs

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"

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: [].}
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: [].}
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: [].}
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: [].}
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: [].}
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: [].}
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: [].}
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: [].}
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: [].}
The cache is discarded and disabled. The GC will reuse its used memory.   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 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 
proc len(a: Rope): int {....gcsafe, extern: "nro$1", raises: [], tags: [].}
The rope's length.   Source   Edit 
proc rope(f: BiggestFloat): Rope {....gcsafe, extern: "nro$1BiggestFloat",
                                   raises: [], tags: [].}
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: [].}
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: [].}
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].}
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

Iterators

iterator items(r: Rope): char {....raises: [], tags: [].}
Iterates over any character in the rope r.   Source   Edit 
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

Made with Nim. Generated: 2024-10-24 00:00:00 UTC