Struct ropey::Rope [] [src]

pub struct Rope<S = DefaultSegmenter> where
    S: GraphemeSegmenter
{ /* fields omitted */ }

A utf8 text rope.

Rope's atomic unit of data is Unicode scalar values (or chars in Rust). Except where otherwise documented, all methods that index into a rope or return an index into a rope do so by char index. This makes the API's intuitive and prevents accidentally creating a Rope with invalid utf8 data.

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 Rope's is extremely cheap, taking only a few instructions and 8 bytes of memory, regardless of text size. This is accomplished by data sharing between Rope clones, and the memory used by clones only grows incrementally as the their contents diverge due to edits. All of this is thread safe, and clones can be sent freely between threads.

Rope tracks line endings and has efficient API's for working with lines. You can convert between char and line index, determining which line a given char is on or the char index of the beginning of a line:

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

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), 18);
assert_eq!(rope.line_to_char(2), 31);

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<DefaultSegmenter>
[src]

[src]

Creates an empty Rope.

[src]

Creates a Rope from a string slice.

Runs in O(N) time.

[src]

Creates a Rope from the output of a reader.

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.

impl<S: GraphemeSegmenter> Rope<S>
[src]

[src]

Creates an empty Rope with a custom grapheme segmenter.

Example

use ropey::segmentation::NullSegmenter;

let rope = Rope::<NullSegmenter>::with_segmenter();

[src]

Creates a Rope with a custom grapheme segmenter from a string slice.

Example

use ropey::segmentation::NullSegmenter;

let rope = Rope::<NullSegmenter>::from_str_with_segmenter("Hello world!");

[src]

Creates a Rope with a custom grapheme segmenter from the output of a reader.

Example

use ropey::segmentation::NullSegmenter;

let rope = Rope::<NullSegmenter>::from_reader_with_segmenter(
    BufReader::new(File::open("my_great_book.txt")?)
)?;

[src]

Total number of bytes in the Rope.

Runs in O(1) time.

[src]

Total number of chars in the Rope.

Runs in O(1) time.

[src]

Total number of lines in the Rope.

Runs in O(1) time.

[src]

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.

[src]

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 and grapheme 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.

[src]

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()).

[src]

Removes the text in the given char index range.

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

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()).

[src]

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()).

[src]

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

[src]

Returns the line index of the given char.

Notes:

  • Lines are zero-indexed.
  • If char_idx is one-past-the-end, then one-past-the-end line index is returned. This is mainly unintuitive for empty ropes, which will return a line index of 1 for a char_idx of zero. Otherwise it behaves as expected.

Panics

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

[src]

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()).

[src]

Returns the char at char_idx.

Panics

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

[src]

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()).

[src]

Returns whether char_idx is a grapheme cluster boundary or not.

Panics

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

[src]

Returns the char index of the grapheme cluster boundary to the left of char_idx.

This excludes any boundary that might be at char_idx itself, unless char_idx is at the beginning of the rope.

Panics

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

[src]

Returns the char index of the grapheme cluster boundary to the right of char_idx.

This excludes any boundary that might be at char_idx itself, unless char_idx is at the end of the rope.

Panics

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

[src]

Gets an immutable slice of the Rope.

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

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()).

[src]

Creates an iterator over the bytes of the Rope.

[src]

Creates an iterator over the chars of the Rope.

[src]

Creates an iterator over the grapheme clusters of the Rope.

[src]

Creates an iterator over the lines of the Rope.

[src]

Creates an iterator over the chunks of the Rope.

[src]

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

Trait Implementations

impl<S: Clone> Clone for Rope<S> where
    S: GraphemeSegmenter
[src]

[src]

Returns a copy of the value. Read more

1.0.0
[src]

Performs copy-assignment from source. Read more

impl<S: GraphemeSegmenter> Debug for Rope<S>
[src]

[src]

Formats the value using the given formatter.

impl<S: GraphemeSegmenter> Display for Rope<S>
[src]

[src]

Formats the value using the given formatter. Read more

impl<S: GraphemeSegmenter> Default for Rope<S>
[src]

[src]

Returns the "default value" for a type. Read more

impl<'a, S1: GraphemeSegmenter, S2: GraphemeSegmenter> PartialEq<Rope<S2>> for Rope<S1>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.

impl<'a, S: GraphemeSegmenter> PartialEq<&'a str> for Rope<S>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.

impl<S: GraphemeSegmenter> PartialEq<str> for Rope<S>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.

impl<'a, S: GraphemeSegmenter> PartialEq<String> for Rope<S>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.

impl<'a, S: GraphemeSegmenter> PartialEq<Cow<'a, str>> for Rope<S>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.

impl<'a, S1: GraphemeSegmenter, S2: GraphemeSegmenter> PartialEq<RopeSlice<'a, S2>> for Rope<S1>
[src]

[src]

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

1.0.0
[src]

This method tests for !=.