Struct Rope 

pub struct Rope { /* private fields */ }

A utf8 text rope.

The time complexity of nearly all edit and query operations on Rope are worst-case O(log N) in the length of the rope. Rope is designed to work efficiently even for huge (in the gigabytes) and pathological (all on one line) texts.

Editing Operations

The editing operations on Rope are insertion and removal of text. For example:

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

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

Query Operations

Rope provides a rich set of efficient query functions, including querying rope length in bytes/chars/lines, fetching individual chars or lines, and converting between different indexing metrics.

For example, to find the starting byte index of a given line:

use ropey::LineType::LF_CR;

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

assert_eq!(rope.line_to_byte_idx(0, LF_CR), 0);
assert_eq!(rope.line_to_byte_idx(1, LF_CR), 23);
assert_eq!(rope.line_to_byte_idx(2, LF_CR), 36);

Slicing

You can take immutable slices of a Rope using slice():

let mut rope = Rope::from_str("Hello みんなさん!");
let middle = rope.slice(3..12);

assert_eq!(middle, "lo みん");

Cloning

Cloning Ropes is extremely cheap, running in O(1) time and taking a small 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.

The primary intended use case for this feature is to allow asynchronous (in the general sense, not necessarily in the async sense) processing of Ropes. For example, saving a large document to disk in a separate thread while the user continues to perform edits.

Implementations

impl Rope

pub fn new() -> Rope

Creates an empty Rope.

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

Creates a Rope from a string slice.

Runs in O(N) time.

pub fn from_reader<T>(reader: T) -> Result<Rope, Error>

where T: Read,

Creates a Rope from the output of a reader.

This is a convenience function, and provides no specific guarantees about performance or internal implementation aside from the runtime complexity listed below.

When more precise control over IO behavior, buffering, etc. is desired, you should handle IO yourself and use RopeBuilder to build the Rope.

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>(&self, writer: T) -> Result<(), Error>

where T: Write,

Writes the contents of the Rope to a writer.

This is a convenience function, and provides no specific guarantees about performance or internal implementation aside from the runtime complexity listed below.

When more precise control over IO behavior, buffering, etc. is desired, you should handle IO yourself and use the Chunks iterator to iterate through the Rope’s contents.

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 insert(&mut self, byte_idx: usize, text: &str)

Inserts text at byte index byte_idx.

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

Example

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

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

Panics

• If byte_idx is out of bounds (i.e. byte_idx > len()).
• If byte_idx is not on a char boundary.

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

Inserts a single char ch at byte index byte_idx.

Runs in O(log N) time.

Example

let mut rope = Rope::from_str("Hello orld!");
rope.insert_char(6, 'w');

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

Panics

• If byte_idx is out of bounds (i.e. byte_idx > len()).
• If byte_idx is not on a char boundary.

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

where R: RangeBounds<usize>,

Removes the text in the given byte index range.

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

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

• If the start of the range is greater than the end.
• If the end of the range is out of bounds (i.e. end > len()).
• If the range ends are not on char boundaries.

pub fn slice<R>(&self, byte_range: R) -> RopeSlice<'_>

where R: RangeBounds<usize>,

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);

Runs in O(log N) time.

Panics

• If the start of the range is greater than the end.
• If the end of the range is out of bounds (i.e. end > len()).
• If the range ends are not on char boundaries.

pub fn len(&self) -> usize

Length of the text in bytes.

Runs in O(1) time.

pub fn len_utf16(&self) -> usize

Total number of utf16 code units that would be in the text if it were encoded as utf16.

Runs in best case O(1) time, worst-case O(log N).

pub fn len_lines(&self, line_type: LineType) -> usize

Total number of lines in the text, according to the passed line type.

Runs in best case O(1) time, worst-case O(log N).

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

Returns whether byte_idx is a char boundary.

Runs in O(log N) time.

Panics

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

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

Returns the byte index of the closest char boundary less than or equal to byte_idx.

Runs in O(log N) time.

Panics

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

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

Returns the byte index of the closest char boundary greater than or equal to byte_idx.

Runs in O(log N) time.

Panics

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

pub fn trailing_line_break_idx(&self, line_type: LineType) -> Option<usize>

If the text ends with a line break, returns its byte index. Otherwise returns None.

Note: a CRLF pair is always treated as a single unit, and thus this function will return the index of the CR in such cases, even with LineType::LF where CR is not on its own recognized as a line break.

Runs in O(log N) time.

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

Returns the byte at byte_idx.

Runs in O(log N) time.

Panics

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

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

Returns the char at byte_idx.

Note that this takes a byte index, not a char index.

Runs in O(log N) time.

Panics

• If byte_idx is out of bounds (i.e. byte_idx >= len()).
• If byte_idx is not a char boundary.

pub fn line(&self, line_idx: usize, line_type: LineType) -> RopeSlice<'_>

Returns the line at line_idx, according to the given line type.

Note: lines are zero-indexed.

Runs in O(log N) time.

Panics

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

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

Returns the chunk containing the byte at byte_idx.

Also returns the byte index of the beginning of the chunk.

Note: for convenience, a one-past-the-end byte_idx returns the last chunk of the RopeSlice.

Runs in O(log N) time.

Panics

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

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

Returns the utf16 code unit index of the given byte.

Ropey stores text internally as utf8, but sometimes it is necessary to interact with external APIs that still use utf16. This function is primarily intended for such situations, and is otherwise not very useful.

Note: if the byte is not on a char boundary, this returns the utf16 code unit index corresponding to the char that the byte belongs to.

Runs in O(log N) time.

Panics

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

pub fn utf16_to_byte_idx(&self, utf16_idx: usize) -> usize

Returns the byte index of the given utf16 code unit.

Ropey stores text internally as utf8, but sometimes it is necessary to interact with external APIs that still use utf16. This function is primarily intended for such situations, and is otherwise not very useful.

Note: if the utf16 code unit is in the middle of a char, returns the byte index of the char that it belongs to.

Runs in O(log N) time.

Panics

Panics if utf16_cu_idx is out of bounds (i.e. utf16_idx > len_utf16()).

pub fn byte_to_line_idx(&self, byte_idx: usize, line_type: LineType) -> usize

Returns the line index of the line that the given byte belongs to.

Notes:

• Counts lines according to the passed line type.
• Lines are zero-indexed. Therefore this is functionally equivalent to counting the line breaks before the specified byte.
• byte_idx can be one-past-the-end, which will return the last line index.

Runs in O(log N) time.

Panics

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

pub fn line_to_byte_idx(&self, line_idx: usize, line_type: LineType) -> usize

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

Notes:

• Counts lines according to the passed line type.
• Lines are zero-indexed.
• line_idx can be one-past-the-end, which will return one-past-the-end byte index.

Runs in O(log N) time.

Panics

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

pub fn bytes(&self) -> Bytes<'_>

Creates an iterator over the bytes of the Rope.

Runs in O(log N) time.

pub fn bytes_at(&self, byte_idx: usize) -> Bytes<'_>

Creates an iterator over the bytes of the Rope, starting at byte byte_idx.

If byte_idx == len() then an iterator at the end of the Rope is created (i.e. next() will return None).

Runs in O(log N) time.

Panics

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

pub fn chars(&self) -> Chars<'_>

Creates an iterator over the chars of the Rope.

Runs in O(log N) time.

pub fn chars_at(&self, byte_idx: usize) -> Chars<'_>

Creates an iterator over the chars of the Rope, starting at byte_idx.

Note that this takes a byte index, not a char index.

If byte_idx == len() then an iterator at the end of the Rope is created (i.e. next() will return None).

Runs in O(log N) time.

Panics

• If byte_idx is out of bounds (i.e. byte_idx > len()).
• If byte_idx is not a char boundary.

pub fn char_indices(&self) -> CharIndices<'_>

Creates an iterator over the chars of the Rope and their byte positions.

On each call to next or prev this iterator returns the byte index where the returned character starts.

Runs in O(log N) time.

pub fn char_indices_at(&self, byte_idx: usize) -> CharIndices<'_>

Creates an iterator over the chars of the Rope and their byte positions, starting at byte_idx.

Note that this takes a byte index, not a char index.

If byte_idx == len() then an iterator at the end of the Rope is created (i.e. next() will return None).

On each call to next or prev this iterator returns the byte index where the returned character starts.

Runs in O(log N) time.

Panics

• If byte_idx is out of bounds (i.e. byte_idx > len()).
• If byte_idx is not a char boundary.

pub fn lines(&self, line_type: LineType) -> Lines<'_>

Creates an iterator over the lines of the Rope.

Note: the iterator will iterate over lines according to the passed line type.

Runs in O(log N) time.

pub fn lines_at(&self, line_idx: usize, line_type: LineType) -> Lines<'_>

Creates an iterator over the lines of the Rope, starting at line line_idx.

Notes:

• The iterator will iterate over lines according to the passed line type.
• If line_idx == len_lines() then an iterator at the end of the Rope is created (i.e. next() will return None).

Runs in O(log N) time.

Panics

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

pub fn chunks(&self) -> Chunks<'_>

Creates an iterator over the chunks of the Rope.

Runs in O(log N) time.

pub fn chunks_at(&self, byte_idx: usize) -> (Chunks<'_>, usize)

Creates an iterator over the chunks of the Rope, with the iterator starting at the chunk containing byte_idx.

Also returns the byte index of the beginning of the chunk to be yielded by next().

If byte_idx == len() an iterator at the end of the Rope (yielding None on a call to next()) is created, and the returned byte index is the end of the text.

Runs in O(log N) time.

Panics

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

pub fn chunk_cursor(&self) -> ChunkCursor<'_>

Creates a cursor for navigating the chunks of the text, starting on the first chunk.

Runs in O(log N) time.

pub fn chunk_cursor_at(&self, byte_idx: usize) -> ChunkCursor<'_>

Creates a cursor for navigating the chunks of the text, with the cursor starting at the chunk containing byte_idx.

For convenience, byte_idx == len() is accepted, and puts the cursor on the last chunk. Note that for non-zero-length texts this is redundant with byte_idx == len() - 1.

Runs in O(log N) time.

Panics

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

pub fn as_str(&self) -> Option<&str>

Returns the text as a string slice if it’s contiguous in memory.

impl Rope

Non-panicking versions of some of Rope’s methods.

pub fn try_insert(&mut self, byte_idx: usize, text: &str) -> Result<(), Error>

Non-panicking version of insert().

On failure this leaves the rope untouched and returns the cause of the failure.

pub fn try_insert_char( &mut self, byte_idx: usize, ch: char, ) -> Result<(), Error>

Non-panicking version of insert_char().

On failure this leaves the rope untouched and returns the cause of the failure.

pub fn try_remove<R>(&mut self, byte_range: R) -> Result<(), Error>

where R: RangeBounds<usize>,

Non-panicking version of remove().

On failure this leaves the rope untouched and returns the cause of the failure.

pub fn try_slice<R>(&self, byte_range: R) -> Result<RopeSlice<'_>, Error>

where R: RangeBounds<usize>,

Non-panicking version of slice().

On failure this returns the cause of the failure.

pub fn get_byte(&self, byte_idx: usize) -> Option<u8>

Non-panicking version of byte().

If byte_idx is out of bounds, returns None.

pub fn get_char(&self, byte_idx: usize) -> Result<char, Error>

Non-panicking version of char().

Will fail if byte_idx is either:

• Not a char boundary.
• Out of bounds.

On failure returns the cause of failure.

pub fn get_line( &self, line_idx: usize, line_type: LineType, ) -> Option<RopeSlice<'_>>

Non-panicking version of line().

If line_idx is out of bounds, returns None.

pub fn get_chunk(&self, byte_idx: usize) -> Option<(&str, usize)>

Non-panicking version of chunk().

If byte_idx is out of bounds, returns None.

Trait Implementations

impl Clone for Rope

fn clone(&self) -> Rope

Returns a duplicate 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<(), Error>

Formats the value using the given formatter.

impl Default for Rope

fn default() -> Rope

Returns the “default value” for a type.

impl Display for Rope

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> From<&'a Rope> for Option<&'a str>

Attempts to borrow the text contents, but will return None if the contents is not contiguous in memory.

Runs in O(1) time.

fn from(r: &'a Rope) -> Option<&'a str>

Converts to this type from the input type.

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

fn from(s: &'a str) -> Rope

Converts to this type from the input type.

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

fn from(s: Cow<'a, str>) -> Rope

Converts to this type from the input type.

impl From<RopeSlice<'_>> for Rope

fn from(rs: RopeSlice<'_>) -> Rope

Converts to this type from the input type.

impl From<String> for Rope

fn from(s: String) -> Rope

Converts to this type from the input type.

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

fn from_iter<T>(iter: T) -> Rope

where T: IntoIterator<Item = &'a str>,

Creates a value from an iterator.

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

fn from_iter<T>(iter: T) -> Rope

where T: IntoIterator<Item = Cow<'a, str>>,

Creates a value from an iterator.

impl FromIterator<String> for Rope

fn from_iter<T>(iter: T) -> Rope

where T: IntoIterator<Item = String>,

Creates a value from an iterator.

impl Hash for Rope

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Rope

fn cmp(&self, other: &Rope) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&str> for Rope

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Rope> for &str

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Rope> for str

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RopeSlice<'_>> for Rope

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for Rope

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Rope

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Rope

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Rope

fn partial_cmp(&self, other: &Rope) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl RopeExt for Rope

fn slice_line(&self, row: usize) -> RopeSlice<'_>

Return a line slice at the given row (0-based) index. including \r if present, but not \n.

fn slice_lines(&self, rows_range: Range<usize>) -> RopeSlice<'_>

Return a slice of rows in the given range (0-based, end exclusive).

fn iter_lines(&self) -> RopeLines<'_>

Return an iterator over all lines in the rope.

fn line_len(&self, row: usize) -> usize

Return the length of the row (0-based) in characters, including \r if present, but not \n.

fn line_start_offset(&self, row: usize) -> usize

Start offset of the line at the given row (0-based) index.

fn offset_to_point(&self, offset: usize) -> Point

Get point (row, column) from the given byte offset.

fn point_to_offset(&self, point: Point) -> usize

Get byte offset from the given point (row, column).

fn position_to_offset(&self, pos: &Position) -> usize

Get the byte offset from the given line, column Position (0-based).

fn offset_to_position(&self, offset: usize) -> Position

Get the line, column Position (0-based) from the given byte offset.

fn line_end_offset(&self, row: usize) -> usize

Line the end offset (including \n) of the line at the given row (0-based) index.

fn lines_len(&self) -> usize

Return the number of lines in the rope.

fn char_at(&self, offset: usize) -> Option<char>

Get char at the given offset (byte).

fn word_range(&self, offset: usize) -> Option<Range<usize>>

Get the word byte range at the given byte offset (0-based).

fn word_at(&self, offset: usize) -> String

Get word at the given byte offset (0-based).

fn offset_utf16_to_offset(&self, offset_utf16: usize) -> usize

Convert offset in UTF-16 to byte offset (0-based).

fn offset_to_offset_utf16(&self, offset: usize) -> usize

Convert byte offset (0-based) to offset in UTF-16.

fn replace(&mut self, range: Range<usize>, new_text: &str)

Replace the text in the given byte range with new text.

fn clip_offset(&self, offset: usize, bias: Bias) -> usize

Get a clipped offset (avoid in a char boundary).

impl Eq for Rope