A type for textual data. A rope is text backed by a tree data structure, rather than a single large continguous array, as is the case for strings.

There are three use cases:

Referencing externally sourced data

Often we interpret large blocks of data sourced from external systems as text. Ideally we would hold onto this without copying the memory, but (as in the case of ByteString which is the most common source of data) before we can treat it as text we have to validate the UTF-8 content. Safety first. We also copy it out of pinned memory, allowing the Haskell runtime to manage the storage.

Interoperating with other libraries

The only constant of the Haskell universe is that you won't have the right combination of {strict, lazy} × {Text, ByteString, String, [Word8], etc} you need for the next function call. The Textual typeclass provides for moving between different text representations. To convert between Rope and something else use fromRope; to construct a Rope from textual content in another type use intoRope.

You can get at the underlying finger tree with the unRope function.

Assembling text to go out

This involves considerable appending of data, very very occaisionally inserting it. Often the pieces are tiny. To add text to a Rope use the append method as below or (<>) from Data.Monoid (like you would have with a Builder).

Output to a Handle can be done efficiently with hWrite.

Get the length of this text, in characters.

Break the text into two pieces at the specified offset.

Examples:

λ> split 0 "abcdef"
("", "abcdef")
λ> split 3 "abcdef"
("abc", "def")
λ> split 6 "abcdef"
("abcdef","")

Going off either end behaves sensibly:

λ> split 7 "abcdef"
("abcdef","")
λ> split (-1) "abcdef"
("", "abcdef")

Insert a new piece of text into an existing Rope at the specified offset.

Examples:

λ> insert 3 "Con" "Def 1"
"DefCon 1"
λ> insert 0 "United " "Nations"
"United Nations"

Does the text contain this character?

We've used it to ask whether there are newlines present in a Rope, for example:

    if contains '\n' text
        then handleComplexCase
        else keepItSimple

Machinery to interpret a type as containing valid Unicode that can be represented as a Rope object.

Implementation notes

Given that Rope is backed by a finger tree, append is relatively inexpensive, plus whatever the cost of conversion is. There is a subtle trap, however: if adding small fragments of that were obtained by slicing (for example) a large ByteString we would end up holding on to a reference to the entire underlying block of memory. This module is optimized to reduce heap fragmentation by letting the Haskell runtime and garbage collector manage the memory, so instances are expected to copy these substrings out of pinned memory.

The ByteString instance requires that its content be valid UTF-8. If not an empty Rope will be returned.

Several of the fromRope implementations are expensive and involve a lot of intermiate allocation and copying. If you're ultimately writing to a handle prefer hWrite which will write directly to the output buffer.

If you know the input bytes are valid UTF-8 encoded characters, then you can use this function to convert to a piece of Rope.

Write the Rope to the given Handle.

import Core.Text
import Core.System -- re-exports stdout

main :: IO ()
main =
  let
    text :: Rope
    text = "Hello World"
  in
    hWrite stdout text

because it's tradition.

Uses hPutBuilder internally which saves all kinds of intermediate allocation and copying because we can go from the ShortTexts in the finger tree to ShortByteString to Builder to the Handle's output buffer in one go.

If you're working in the Program monad, then write provides an efficient way to write a Rope to stdout.

Access the finger tree underlying the Rope. You'll want the following imports:

import qualified Data.FingerTree as F  -- from the fingertree package
import qualified Data.Text.Short as S  -- from the text-short package

The length of the Rope, in characters. This is the monoid used to structure the finger tree underlying the Rope.