Crate ropey[−][src]

Ropey is a utf8 text rope library, designed to be the backing text buffer for applications such as text editors. Ropey is fast, Unicode-safe, has low memory overhead, and can handle huge texts and memory-incoherent edits without trouble.

Ropey's atomic unit of text is Unicode scalar values (or chars in Rust) encoded as utf8. All of Ropey's editing and slicing operations are done in terms of char indices which prevents accidental creation of invalid utf8 data.

The library is made up of four main components:

  • Rope: the main editable text buffer type.
  • RopeSlice: an immutable view into part of a Rope.
  • iter: iterators over Rope/RopeSlice data.
  • RopeBuilder: an efficient incremental Rope builder.

A Basic Example

Let's say we want to open up a file, replace the 516th line (the writing was terrible!), and save it back to disk. It's contrived, but will give a good sampling of the APIs and how they work together.

use std::fs::File;
use std::io::{BufReader, BufWriter};
use ropey::Rope;

// Load the file into a Rope.
let mut text = Rope::from_reader(
    BufReader::new(File::open("my_great_book.txt")?)
)?;

// Make sure there are at least 516 lines.
if text.len_lines() >= 516 {
    // Print the 516th line (zero-indexed) to see the terrible
    // writing.
    println!("{}", text.line(515));

    // Get the char indices of the start/end of the line.
    let start_idx = text.line_to_char(515);
    let end_idx = text.line_to_char(516);

    // Remove that terrible writing!
    text.remove(start_idx..end_idx);

    // ...and replace it with something better.
    text.insert(start_idx, "The flowers are... so... dunno.\n");

    // Let's print our changes, along with the previous few lines
    // for context.  Gotta make sure the writing works!
    let start_idx = text.line_to_char(511);
    let end_idx = text.line_to_char(516);
    println!("{}", text.slice(start_idx..end_idx));
}

// Write the file back out to disk.
text.write_to(
    BufWriter::new(File::create("my_great_book.txt")?)
)?;

Low-level APIs

Ropey also provides access to some of its low-level APIs, enabling client code to efficiently work with a Rope's data and implement new functionality. The most important of those API's are:

  • The chunk_at_*() chunk-fetching methods of Rope and RopeSlice.
  • The Chunks iterator.
  • The functions in str_utils for operating on &str slices.

Internally, each Rope stores text as a segemented collection of utf8 strings. The chunk-fetching methods and Chunks iterator provide direct access to those strings (or "chunks") as &str slices, allowing client code to work directly with the underlying utf8 data.

The chunk-fetching methods and str_utils functions are the basic building blocks that Ropey itself uses to build much of its functionality. For example, the Rope::byte_to_char() method can be reimplemented as a free function like this:

use ropey::{
    Rope,
    str_utils::byte_to_char_idx
};

fn byte_to_char(rope: &Rope, byte_idx: usize) -> usize {
    let (chunk, b, c, _) = rope.chunk_at_byte(byte_idx);
    c + byte_to_char_idx(chunk, byte_idx - b)
}

And this will be just as efficient as Ropey's implementation.

The chunk-fetching methods in particular are among the fastest functions that Ropey provides, generally operating in the sub-hundred nanosecond range for medium-sized (~200kB) documents on recent-ish computer systems.

A Note About Line Endings

Some of Ropey's APIs use the concept of line breaks or lines of text. In all such APIs, Ropey treats the following unicode sequences as line breaks:

  • U+000A — LF (Line Feed)
  • U+000B — VT (Vertical Tab)
  • U+000C — FF (Form Feed)
  • U+000D — CR (Carriage Return)
  • U+0085 — NEL (Next Line)
  • U+2028 — Line Separator
  • U+2029 — Paragraph Separator
  • U+000D U+000A — CRLF (Carriage Return + Line Feed)

Additionally, Ropey treats line breaks as being a part of the line that they mark the end of. That is to say, lines begin immediately after a line break.

CRLF pairs are always treated as a single line break, and are never split across chunks. Note, however, that slicing can still split them.

Modules

iter

Iterators over a Rope's data.
str_utils

Utility functions for utf8 string slices.

Structs

Rope

A utf8 text rope.
RopeBuilder

An efficient incremental Rope builder.
RopeSlice

An immutable view into part of a Rope.