Struct Rope

Source

pub struct Rope { /* private fields */ }

Expand description

A UTF-8 text rope.

Implementations§

Source §

impl Rope

Source

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

Returns the byte at byte_index.

§Panics

Panics if the byte index is out of bounds (i.e. greater than or equal to byte_len()).

§Examples

let r = Rope::from("bar");

assert_eq!(r.byte(0), b'b');
assert_eq!(r.byte(1), b'a');
assert_eq!(r.byte(2), b'r');

Source

pub fn byte_len(&self) -> usize

Returns the length of the Rope in bytes.

§Examples

let r = Rope::from("ƒoo");

assert_eq!(r.byte_len(), 4);

Source

pub fn byte_of_line(&self, line_offset: usize) -> usize

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

§Panics

Panics if the line offset is out of bounds (i.e. greater than line_len()).

§Examples

let r = Rope::from("ƒoo\nbär\r\nbaz");

assert_eq!(r.byte_of_line(0), 0);
assert_eq!(r.byte_of_line(1), "ƒoo\n".len());
assert_eq!(r.byte_of_line(2), "ƒoo\nbär\r\n".len());
assert_eq!(r.byte_of_line(r.line_len()), r.byte_len());

Source

pub fn byte_of_utf16_code_unit(&self, utf16_offset: usize) -> usize

Available on crate feature utf16-metric only.

Returns the byte offset corresponding to the given UTF-16 code unit offset.

§Panics

Panics if the UTF-16 code unit offset is out of bounds (i.e. greater than utf16_len()) or if it doesn’t lie on a code point boundary.

§Examples

// The "𐐀" character is encoded using two code units in UTF-16 and
// four bytes in UTF-8.
let r = Rope::from("a𐐀b");
assert_eq!(r.byte_of_utf16_code_unit(3), 5);

Source

pub fn byte_slice<R>(&self, byte_range: R) -> RopeSlice<'_>
where R: RangeBounds<usize>,

Returns an immutable slice of the Rope in the specified byte range, where the start and end of the range are interpreted as offsets.

§Panics

Panics if the start or the end of the byte range don’t lie on a code point boundary, if the start is greater than the end or if the end is out of bounds (i.e. greater than byte_len()).

§Examples

let r = Rope::from("🗻∈🌏");

assert_eq!(r.byte_slice(..4), "🗻");
assert_eq!(r.byte_slice(4..7), "∈");
assert_eq!(r.byte_slice(7..), "🌏");

Source

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

Returns an iterator over the bytes of this Rope.

§Examples

let r = Rope::from("foo");

let mut bytes = r.bytes();

assert_eq!(Some(b'f'), bytes.next());
assert_eq!(Some(b'o'), bytes.next());
assert_eq!(Some(b'o'), bytes.next());
assert_eq!(None, bytes.next());

Source

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

Returns an iterator over the chars of this Rope.

§Examples

let r = Rope::from("🐻‍❄️");

let mut chars = r.chars();

assert_eq!(Some('🐻'), chars.next());
assert_eq!(Some('\u{200d}'), chars.next());
assert_eq!(Some('❄'), chars.next());
assert_eq!(Some('\u{fe0f}'), chars.next());
assert_eq!(None, chars.next());

Source

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

Returns an iterator over the chunks of this Rope.

Source

pub fn delete<R>(&mut self, byte_range: R)
where R: RangeBounds<usize>,

Deletes the contents of the Rope within the specified byte range, where the start and end of the range are interpreted as offsets.

§Panics

Panics if the start or the end of the byte range don’t lie on a code point boundary, if the start is greater than the end or if the end is out of bounds (i.e. greater than byte_len()).

§Examples

let mut r = Rope::from("Hello Earth 🌎!");

r.delete(5..16);
assert_eq!(r, "Hello!");

Source

pub fn graphemes(&self) -> Graphemes<'_> ⓘ

Available on crate feature graphemes only.

Returns an iterator over the extended grapheme clusters of this Rope.

§Examples

let r = Rope::from("arg!\r\n🐻‍❄️");

let mut graphemes = r.graphemes();

assert_eq!(Some("a"), graphemes.next().as_deref());
assert_eq!(Some("r"), graphemes.next().as_deref());
assert_eq!(Some("g"), graphemes.next().as_deref());
assert_eq!(Some("!"), graphemes.next().as_deref());
assert_eq!(Some("\r\n"), graphemes.next().as_deref());
assert_eq!(Some("🐻‍❄️"), graphemes.next().as_deref());
assert_eq!(None, graphemes.next());

Source

pub fn insert<T>(&mut self, byte_offset: usize, text: T)
where T: AsRef<str>,

Inserts text in the Rope at the given byte offset.

§Panics

Panics if the byte offset doesn’t lie on a code point boundary or if it’s out of bounds (i.e. greater than byte_len()).

§Examples

let mut r = Rope::from("Hello Earth!");

r.insert(11, " 🌎");
assert_eq!(r, "Hello Earth 🌎!");

Source

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

Returns true if the given byte offset lies on a char boundary.

§Panics

Panics if the byte offset is out of bounds (i.e. greater than byte_len()).

§Examples

let r = Rope::from("Löwe 老虎 Léopard");

assert!(r.is_char_boundary(0));
assert!(r.is_char_boundary(r.byte_len()));
assert!(r.is_char_boundary(6)); // between ' ' and '老'
assert!(!r.is_char_boundary(2)); // between the 1st and 2nd byte of 'ö'

Source

pub fn is_empty(&self) -> bool

Returns true if the Rope’s byte length is zero.

§Examples

let mut r = Rope::new();
assert!(r.is_empty());

r.insert(0, "hey");
assert!(!r.is_empty());

Source

pub fn is_grapheme_boundary(&self, byte_offset: usize) -> bool

Available on crate feature graphemes only.

Returns true if the given byte offset lies on a grapheme cluster boundary.

§Panics

Panics if the byte offset is out of bounds (i.e. greater than byte_len()).

§Examples

let r = Rope::from("aargh!\r\n🐻‍❄️");

assert!(r.is_grapheme_boundary(0));
assert!(r.is_grapheme_boundary(r.byte_len()));
assert!(!r.is_grapheme_boundary(7)); // between '\r' and '\n'
assert!(r.is_grapheme_boundary(8)); // between '\n' and '🐻‍❄️'
assert!(!r.is_grapheme_boundary(12)); // between the 1st and 2nd code point of '🐻‍❄️'

Source

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

Returns the line at line_index, without its line terminator.

If you want to include the line break consider taking a line_slice() in the line_index..line_index + 1 range.

§Panics

Panics if the line index is out of bounds (i.e. greater than or equal to line_len()).

§Examples

let r = Rope::from("foo\nbar\r\nbaz");

assert_eq!(r.line(0), "foo");
assert_eq!(r.line(1), "bar");
assert_eq!(r.line(2), "baz");

Source

pub fn line_len(&self) -> usize

Returns the number of lines in the Rope.

The final line break is optional and doesn’t count as a separate empty line.

§Examples

let mut r = Rope::new();

assert_eq!(r.line_len(), 0);

r.insert(0, "a");
assert_eq!(r.line_len(), 1);

r.insert(1, "\n");
assert_eq!(r.line_len(), 1);

r.insert(2, "b");
assert_eq!(r.line_len(), 2);

r.insert(3, "\r\n");
assert_eq!(r.line_len(), 2);

Source

pub fn line_of_byte(&self, byte_offset: usize) -> usize

Returns the line offset of the given byte.

§Panics

Panics if the byte offset is out of bounds (i.e. greater than byte_len()).

§Examples

let r = Rope::from("foo\nbar\r\nbaz");

assert_eq!(r.line_of_byte(0), 0);
assert_eq!(r.line_of_byte(3), 0);
assert_eq!(r.line_of_byte(4), 1);
assert_eq!(r.line_of_byte(8), 1); // between the '\r' and the '\n'
assert_eq!(r.line_of_byte(r.byte_len()), 2);

Source

pub fn line_slice<R>(&self, line_range: R) -> RopeSlice<'_>
where R: RangeBounds<usize>,

Returns an immutable slice of the Rope in the specified line range, where the start and end of the range are interpreted as offsets.

§Panics

Panics if the start is greater than the end or if the end is out of bounds (i.e. greater than line_len()).

§Examples

let r = Rope::from("foo\nbar\r\nbaz\nfoobar\n");

assert_eq!(r.line_slice(..1), "foo\n");
assert_eq!(r.line_slice(1..3), "bar\r\nbaz\n");
assert_eq!(r.line_slice(3..4), "foobar\n");
assert_eq!(r.line_slice(4..), "");

Source

pub fn lines(&self) -> Lines<'_> ⓘ

Returns an iterator over the lines of this Rope, not including the line terminators.

The final line break is optional and doesn’t cause the iterator to return a final empty line.

If you want to include the line breaks consider using the raw_lines() method instead.

§Examples

let r = Rope::from("foo\nbar\r\nbaz\n");

let mut lines = r.lines();

assert_eq!("foo", lines.next().unwrap());
assert_eq!("bar", lines.next().unwrap());
assert_eq!("baz", lines.next().unwrap());
assert_eq!(None, lines.next());

Source

pub fn raw_lines(&self) -> RawLines<'_> ⓘ

Returns an iterator over the lines of this Rope, including the line terminators.

The final line break is optional and doesn’t cause the iterator to return a final empty line.

If you don’t want to include the line breaks consider using the lines() method instead.

§Examples

let mut r = Rope::from("foo\nbar\r\nbaz");

let mut raw_lines = r.raw_lines();

assert_eq!("foo\n", raw_lines.next().unwrap());
assert_eq!("bar\r\n", raw_lines.next().unwrap());
assert_eq!("baz", raw_lines.next().unwrap());
assert_eq!(None, raw_lines.next());

r.insert(r.byte_len(), "\n");

let mut raw_lines = r.raw_lines();

assert_eq!("foo\n", raw_lines.next().unwrap());
assert_eq!("bar\r\n", raw_lines.next().unwrap());
assert_eq!("baz\n", raw_lines.next().unwrap());
assert_eq!(None, raw_lines.next());

Source

pub fn new() -> Self

Returns a new empty Rope.

Source

pub fn replace<R, T>(&mut self, byte_range: R, text: T)
where R: RangeBounds<usize>, T: AsRef<str>,

Replaces the contents of the Rope within the specified byte range with the given string, where the start and end of the range are interpreted as byte offsets.

§Panics

Panics if the start or the end of the byte range don’t lie on a code point boundary, if the start is greater than the end or if the end is out of bounds (i.e. greater than byte_len()).

§Examples

let mut r = Rope::from("Hello Earth 🌎!");

r.replace(6..16, "Saturn 🪐");
assert_eq!(r, "Hello Saturn 🪐!");

Source

pub fn utf16_len(&self) -> usize

Available on crate feature utf16-metric only.

Returns the number of UTF-16 code units the Rope would have if it stored its text as UTF-16 instead of UTF-8.

§Examples

// The "🐸" emoji is encoded using two UTF-16 code units.
let r = Rope::from("abc🐸");
assert_eq!(r.utf16_len(), 5);

Source

pub fn utf16_code_unit_of_byte(&self, byte_offset: usize) -> usize

Available on crate feature utf16-metric only.

Returns the UTF-16 code unit offset corresponding to the given byte offset.

§Panics

Panics if the byte offset is out of bounds (i.e. greater than byte_len()).

§Examples

// The "𐐀" character is encoded using two code units in UTF-16 and
// four bytes in UTF-8.
let r = Rope::from("a𐐀b");
assert_eq!(r.utf16_code_unit_of_byte(5), 3);

Source

pub fn utf16_slice<R>(&self, utf16_range: R) -> RopeSlice<'_>
where R: RangeBounds<usize>,

Available on crate feature utf16-metric only.

Returns an immutable slice of the Rope in the specified UTF-16 code unit range, where the start and end of the range are interpreted as offsets.

§Panics

Panics if the start is greater than the end or if the end is out of bounds (i.e. greater than utf16_len()).

§Examples

// Both "𐐀" and "🐸" are encoded using two code units in UTF-16.
let r = Rope::from("ab𐐀de🐸");

assert_eq!(r.utf16_slice(..4), "ab𐐀");
assert_eq!(r.utf16_slice(5..), "e🐸");
assert_eq!(r.utf16_slice(2..4), "𐐀");