Struct ropey::RopeSlice

pub struct RopeSlice<'a>(_);

An immutable view into part of a Rope.

Just like standard &str slices, RopeSlices behave as if the text in their range is the only text that exists. All indexing is relative to the start of their range, and all iterators and methods that return text truncate that text to the range of the slice.

In other words, the behavior of a RopeSlice is always identical to that of a full Rope created from the same text range. Nothing should be surprising here.

Implementations

impl<'a> RopeSlice<'a>

pub fn len_bytes(&self) -> usize

Total number of bytes in the RopeSlice.

Runs in O(1) time.

pub fn len_chars(&self) -> usize

Total number of chars in the RopeSlice.

Runs in O(1) time.

pub fn len_lines(&self) -> usize

Total number of lines in the RopeSlice.

Runs in O(1) time.

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 byte(&self, byte_idx: usize) -> u8

Returns the byte at byte_idx.

Panics

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

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<'a>

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) -> (&'a 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) -> (&'a 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
) -> (&'a 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 slice 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 as_str(&self) -> Option<&'a str>

Returns the entire contents of the RopeSlice as a &str if possible.

This is useful for optimizing cases where the slice is only a few characters or words, and therefore has a high chance of being contiguous in memory.

For large slices this method will typically fail and return None because large slices usually cross chunk boundaries in the rope.

(Also see the From impl for converting to a Cow<str>.)

Runs in O(1) time.

pub fn slice<R>(&self, char_range: R) -> Selfwhere
    R: RangeBounds<usize>,

Returns a sub-slice of the RopeSlice in the given char index range.

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

Panics

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

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

Creates an iterator over the bytes of the RopeSlice.

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

Creates an iterator over the chars of the RopeSlice.

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

Creates an iterator over the lines of the RopeSlice.

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

Creates an iterator over the chunks of the RopeSlice.

Trait Implementations

impl<'a> Clone for RopeSlice<'a>

fn clone(&self) -> RopeSlice<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for RopeSlice<'a>

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

Formats the value using the given formatter.

impl<'a> Display for RopeSlice<'a>

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

Formats the value using the given formatter.

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

Creates a RopeSlice directly from a string slice.

The useful applications of this are actually somewhat narrow. It is intended primarily as an aid when implementing additional functionality on top of Ropey, where you may already have access to a rope chunk and want to directly create a RopeSlice from it, avoiding the overhead of going through the slicing APIs.

Although it is possible to use this to create RopeSlices from arbitrary strings, doing so is not especially useful. For example, Ropes and RopeSlices can already be directly compared for equality with strings and string slices.

Runs in O(N) time, where N is the length of the string slice.

fn from(text: &'a str) -> Self

Converts to this type from the input type.

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

Attempts to borrow the contents of the slice, but will convert to an owned string if the contents is not contiguous in memory.

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

fn from(s: RopeSlice<'a>) -> Self

Converts to this type from the input type.

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

Will share data where possible.

Runs in O(log N) time.

fn from(s: RopeSlice<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<RopeSlice<'a>> for String

fn from(s: RopeSlice<'a>) -> Self

Converts to this type from the input type.

impl<'a> Ord for RopeSlice<'a>

fn cmp(&self, other: &RopeSlice<'a>) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<'a, 'b> PartialEq<&'b str> for RopeSlice<'a>

fn eq(&self, other: &&'b 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Cow<'b, str>> for RopeSlice<'a>

fn eq(&self, other: &Cow<'b, 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<RopeSlice<'a>> for &'b str

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<RopeSlice<'a>> for Cow<'b, str>

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<RopeSlice<'b>> for RopeSlice<'a>

fn eq(&self, other: &RopeSlice<'b>) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialOrd<RopeSlice<'b>> for RopeSlice<'a>

fn partial_cmp(&self, other: &RopeSlice<'b>) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a> Copy for RopeSlice<'a>

impl<'a> Eq for RopeSlice<'a>