# Module ropes

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 Nimrod 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

    PRope = ref TRope

  empty rope is represented by nil

# Procs

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

  the rope's length

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

  Converts a string to a rope.

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

  Converts an int to a rope.

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

  Converts a float to a rope.

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

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

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

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

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

  the concatenation operator for ropes.

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

  the concatenation operator for ropes.

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

  the concatenation operator for ropes.

    proc `&`(a: openarray[PRope]): PRope {.rtl, extern: "nroConcOpenArray",
                                           raises: [], tags: [].}

  the concatenation operator for an openarray of ropes.

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

  adds b to the rope a.

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

  adds b to the rope a.

    proc `[]`(r: PRope; i: int): char {.rtl, 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.

    proc write(f: TFile; r: PRope) {.rtl, extern: "nro$1", raises: [EIO],
                                     tags: [FWriteIO].}

  writes a rope to a file.

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

  converts a rope back to a string.

    proc `%`(frmt: string; args: openarray[PRope]): PRope {.rtl,
        extern: "nroFormat", raises: [EInvalidValue, EInvalidValue], tags: [].}

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

    proc addf(c: var PRope; frmt: string; args: openarray[PRope]) {.rtl,
        extern: "nro$1", raises: [EInvalidValue], tags: [].}

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

    proc equalsFile(r: PRope; f: TFile): bool {.rtl, extern: "nro$1File",
        raises: [E_Base], tags: [FReadIO].}

  returns true if the contents of the file f equal r.

    proc equalsFile(r: PRope; f: string): bool {.rtl, extern: "nro$1Str",
        raises: [EOutOfMemory, E_Base], tags: [FReadIO].}

  returns true if the contents of the file f equal r. If f does not exist, false is returned.

# Iterators

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

  iterates over any leaf string in the rope r.

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

  iterates over any character in the rope r.

Generated: 2013-05-21 09:55:16 UTC