Struct ropey::Rope

pub struct Rope { /* fields omitted */ }

A utf8 text rope.

The primary editing operations available for Rope are insertion of text, deletion of text, splitting a Rope in two, and appending one Rope to another. For example:

let mut rope = Rope::from_str("Hello みんなさん!");
rope.remove(6..11);
rope.insert(6, "world");

assert_eq!(rope, "Hello world!");

Cloning Ropes is extremely cheap, running in O(1) time and taking a constant amount of memory for the new clone, regardless of text size. This is accomplished by data sharing between Rope clones. The memory used by clones only grows incrementally as the their contents diverge due to edits. All of this is thread safe, so clones can be sent freely between threads.

Rope tracks line endings and utf8 char boundaries, and has efficient APIs for working with both. For example, you can freely convert between byte, char, and line indices:

let rope = Rope::from_str("Hello みんなさん!\nHow are you?\nThis text has multiple lines!");

assert_eq!(rope.byte_to_char(15), 9);
assert_eq!(rope.byte_to_char(41), 31);

assert_eq!(rope.char_to_line(5), 0);
assert_eq!(rope.char_to_line(21), 1);

assert_eq!(rope.line_to_char(0), 0);
assert_eq!(rope.line_to_char(1), 13);
assert_eq!(rope.line_to_char(2), 26);

Rope is written to be fast and memory efficient. Except where otherwise documented, all editing and query operations execute in worst-case O(log N) time in the length of the rope. It is designed to work efficiently even for huge (in the gigabytes) and pathological (all on one line) texts. It should be able to handle just about anything you can throw at it.

Methods

impl Rope

pub fn new() -> Self

Creates an empty Rope.

pub fn from_str(text: &str) -> Self

Creates a Rope from a string slice.

Runs in O(N) time.

pub fn from_reader<T: Read>(reader: T) -> Result<Self>

Creates a Rope from the output of a reader.

This is a convenience function. To do more sophisticated text loading, see RopeBuilder.

Runs in O(N) time.

Errors

• If the reader returns an error, from_reader stops and returns that error.
• If non-utf8 data is encountered, an IO error with kind InvalidData is returned.

Note: some data from the reader is likely consumed even if there is an error.

pub fn write_to<T: Write>(&self, writer: T) -> Result<()>

Writes the contents of the Rope to a writer.

This is a convenience function. To do more sophisticated text output, see the Chunks iterator.

Runs in O(N) time.

Errors

• If the writer returns an error, write_to stops and returns that error.

Note: some data may have been written even if an error is returned.

pub fn len_bytes(&self) -> usize

Total number of bytes in the Rope.

Runs in O(1) time.

pub fn len_chars(&self) -> usize

Total number of chars in the Rope.

Runs in O(1) time.

pub fn len_lines(&self) -> usize

Total number of lines in the Rope.

Runs in O(1) time.

pub fn capacity(&self) -> usize

Total size of the Rope's text buffer space, in bytes.

This includes unoccupied text buffer space. You can calculate the unoccupied space with capacity() - len_bytes(). In general, there will always be some unoccupied buffer space.

Runs in O(N) time.

pub fn shrink_to_fit(&mut self)

Shrinks the Rope's capacity to the minimum possible.

This will rarely result in capacity() == len_bytes(). Rope stores text in a sequence of fixed-capacity chunks, so an exact fit only happens for texts that are both a precise multiple of that capacity and have code point boundaries that line up exactly with the capacity boundaries.

After calling this, the difference between capacity() and len_bytes() is typically under 1KB per megabyte of text in the Rope.

NOTE: calling this on a Rope clone causes it to stop sharing all data with its other clones. In such cases you will very likely be increasing total memory usage despite shrinking the Rope's capacity.

Runs in O(N) time, and uses O(log N) additional space during shrinking.

pub fn insert(&mut self, char_idx: usize, text: &str)

Inserts text at char index char_idx.

Runs in O(M + log N) time, where N is the length of the Rope and M is the length of text.

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn insert_char(&mut self, char_idx: usize, ch: char)

Inserts a single char ch at char index char_idx.

Runs in O(log N) time, where N is the length of the Rope.

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn remove<R: CharIdxRange>(&mut self, char_range: R)

Removes the text in the given char index range.

Uses range syntax, e.g. 2..7, 2.., etc. The range is in char indices.

Runs in O(M + log N) time, where N is the length of the Rope and M is the length of the range being removed.

Example

let mut rope = Rope::from_str("Hello world!");
rope.remove(5..);

assert_eq!("Hello", rope);

Panics

Panics if the start of the range is greater than the end, or if the end is out of bounds (i.e. end > len_chars()).

pub fn split_off(&mut self, char_idx: usize) -> Self

Splits the Rope at char_idx, returning the right part of the split.

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn append(&mut self, other: Self)

Appends a Rope to the end of this one, consuming the other Rope.

pub fn byte_to_char(&self, byte_idx: usize) -> usize

Returns the char index of the given byte.

Notes:

• If the byte is in the middle of a multi-byte char, returns the index of the char that the byte belongs to.
• byte_idx can be one-past-the-end, which will return one-past-the-end char index.

Panics

Panics if byte_idx is out of bounds (i.e. byte_idx > len_bytes()).

pub fn byte_to_line(&self, byte_idx: usize) -> usize

Returns the line index of the given byte.

Notes:

• Lines are zero-indexed. This is functionally equivalent to counting the line endings before the specified byte.
• byte_idx can be one-past-the-end, which will return the last line index.

Panics

Panics if byte_idx is out of bounds (i.e. byte_idx > len_bytes()).

pub fn char_to_byte(&self, char_idx: usize) -> usize

Returns the byte index of the given char.

Notes:

• char_idx can be one-past-the-end, which will return one-past-the-end byte index.

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn char_to_line(&self, char_idx: usize) -> usize

Returns the line index of the given char.

Notes:

• Lines are zero-indexed. This is functionally equivalent to counting the line endings before the specified char.
• char_idx can be one-past-the-end, which will return the last line index.

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn line_to_byte(&self, line_idx: usize) -> usize

Returns the byte index of the start of the given line.

Notes:

• Lines are zero-indexed.
• line_idx can be one-past-the-end, which will return one-past-the-end byte index.

Panics

Panics if line_idx is out of bounds (i.e. line_idx > len_lines()).

pub fn line_to_char(&self, line_idx: usize) -> usize

Returns the char index of the start of the given line.

Notes:

• Lines are zero-indexed.
• line_idx can be one-past-the-end, which will return one-past-the-end char index.

Panics

Panics if line_idx is out of bounds (i.e. line_idx > len_lines()).

pub fn char(&self, char_idx: usize) -> char

Returns the char at char_idx.

Panics

Panics if char_idx is out of bounds (i.e. char_idx >= len_chars()).

pub fn line(&self, line_idx: usize) -> RopeSlice

Returns the line at line_idx.

Note: lines are zero-indexed.

Panics

Panics if line_idx is out of bounds (i.e. line_idx >= len_lines()).

pub fn chunk_at_byte(&self, byte_idx: usize) -> (&str, usize, usize, usize)

Returns the chunk containing the given byte index.

Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.

The return value is organized as (chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx).

Panics

Panics if byte_idx is out of bounds (i.e. byte_idx > len_bytes()).

pub fn chunk_at_char(&self, char_idx: usize) -> (&str, usize, usize, usize)

Returns the chunk containing the given char index.

Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.

The return value is organized as (chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx).

Panics

Panics if char_idx is out of bounds (i.e. char_idx > len_chars()).

pub fn chunk_at_line_break(     &self,     line_break_idx: usize ) -> (&str, usize, usize, usize)

Returns the chunk containing the given line break.

Also returns the byte and char indices of the beginning of the chunk and the index of the line that the chunk starts on.

Note: for convenience, both the beginning and end of the rope are considered line breaks for the purposes of indexing. For example, in the string "Hello \n world!" 0 would give the first chunk, 1 would give the chunk containing the newline character, and 2 would give the last chunk.

The return value is organized as (chunk, chunk_byte_idx, chunk_char_idx, chunk_line_idx).

Panics

Panics if line_break_idx is out of bounds (i.e. line_break_idx > len_lines()).

pub fn slice<R: CharIdxRange>(&self, char_range: R) -> RopeSlice

Gets an immutable slice of the Rope.

Uses range syntax, e.g. 2..7, 2.., etc.

Example

let rope = Rope::from_str("Hello world!");
let slice = rope.slice(..5);

assert_eq!("Hello", slice);

Panics

Panics if the start of the range is greater than the end, or if the end is out of bounds (i.e. end > len_chars()).

Important traits for Bytes<'a>

impl<'a> Iterator for Bytes<'a> type Item = u8;

pub fn bytes(&self) -> Bytes

Creates an iterator over the bytes of the Rope.

Important traits for Chars<'a>

impl<'a> Iterator for Chars<'a> type Item = char;

pub fn chars(&self) -> Chars

Creates an iterator over the chars of the Rope.

Important traits for Lines<'a>

impl<'a> Iterator for Lines<'a> type Item = RopeSlice<'a>;

pub fn lines(&self) -> Lines

Creates an iterator over the lines of the Rope.

Important traits for Chunks<'a>

impl<'a> Iterator for Chunks<'a> type Item = &'a str;

pub fn chunks(&self) -> Chunks

Creates an iterator over the chunks of the Rope.

pub fn to_string(&self) -> String

Returns the entire text of the Rope as a newly allocated String.

Runs in O(N) time.

Trait Implementations

impl Clone for Rope

fn clone(&self) -> Rope

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rope

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Display for Rope

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Rope

fn default() -> Self

Returns the "default value" for a type.

impl PartialEq<Rope> for Rope

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<&'a str> for Rope

fn eq(&self, other: &&'a str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Rope> for &'a str

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<str> for Rope

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Rope> for str

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<String> for Rope

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Rope> for String

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Cow<'a, str>> for Rope

fn eq(&self, other: &Cow<'a, str>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Rope> for Cow<'a, str>

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<Rope> for RopeSlice<'a>

fn eq(&self, other: &Rope) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<RopeSlice<'a>> for Rope

fn eq(&self, other: &RopeSlice<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.