Struct strcursor::StrCursor

pub struct StrCursor<'a> {
    // some fields omitted
}

This type represents a cursor into a string slice; that is, in addition to having a beginning and end, it also has a current position between those two. This position can be seeked left and right within those bounds.

Note: the cursor may validly be positioned at the end of the string. That is, in a position where there are no code points or grapheme clusters to the right of the cursor, and the entire contents of the string is to the left of the cursor.

The main reason for this is that sometimes, you want the ability to do things like "advance a character", and the existing APIs for this can be somewhat verbose.

In addition, unstable support for grapheme clusters is exposed by the standard library, which conflicts with the stable support provided by the unicode-segmentation crate, which makes doing "the right thing" painful. StrCursor exposes grapheme clusters by default, and makes them cleaner to work with.

The cursor guarantees the following at all times:

• The cursor position cannot be outside of the original string slice it was constructed with.
• The cursor position cannot lie between Unicode code points, meaning that you cannot generate an invalid string slice from a cursor.
• If the code point-specific methods are not used, the cursor will always lie between grapheme clusters.

This last point is somewhat important: the cursor is designed to favour operating on grapheme clusters, rather than code points. If you misalign the cursor with respect to grapheme clusters, the behaviour of methods that deal with grapheme clusters is officially undefined, but is generally well-behaved.

The methods that operate on the cursor will either return a fresh Option<StrCursor> (depending on whether the seek operation is valid or not), or mutate the existing cursor (in which case, they will panic if the seek operation is not valid).

Methods

impl<'a> StrCursor<'a>

fn new_at_start(s: &'a str) -> StrCursor<'a>

Create a new cursor at the start of s.

fn new_at_end(s: &'a str) -> StrCursor<'a>

Create a new cursor past at the end of s.

fn new_at_left_of_byte_pos(s: &'a str, byte_pos: usize) -> StrCursor<'a>

Create a new cursor at the first grapheme cluster which begins at or to the left of the given byte position.

fn new_at_right_of_byte_pos(s: &'a str, byte_pos: usize) -> StrCursor<'a>

Create a new cursor at the first grapheme cluster which begins at or to the right of the given byte position.

fn new_at_cp_left_of_byte_pos(s: &'a str, byte_pos: usize) -> StrCursor<'a>

Create a new cursor at the first code point which begins at or to the left of the given byte position.

Note

Where possible, you should prefer new_at_left_of_byte_pos.

fn new_at_cp_right_of_byte_pos(s: &'a str, byte_pos: usize) -> StrCursor<'a>

Create a new cursor at the first code point which begins at or to the right of the given byte position.

Note

Where possible, you should prefer new_at_right_of_byte_pos.

fn at_prev(self) -> Option<StrCursor<'a>>

Returns a new cursor at the beginning of the previous grapheme cluster, or None if the cursor is currently positioned at the beginning of the string.

fn at_next(self) -> Option<StrCursor<'a>>

Returns a new cursor at the beginning of the next grapheme cluster, or None if the cursor is currently positioned at the end of the string.

fn at_prev_cp(self) -> Option<StrCursor<'a>>

Returns a new cursor at the beginning of the previous code point, or None if the cursor is currently positioned at the beginning of the string.

Note

Where possible, you should prefer at_prev.

fn at_next_cp(self) -> Option<StrCursor<'a>>

Returns a new cursor at the beginning of the next code point, or None if the cursor is currently positioned at the end of the string.

Note

Where possible, you should prefer at_next.

fn seek_prev(&mut self)

Seeks the cursor to the beginning of the previous grapheme cluster.

Panics

If the cursor is currently at the start of the string, then this function will panic.

fn seek_next(&mut self)

Seeks the cursor to the beginning of the next grapheme cluster.

Panics

If the cursor is currently at the end of the string, then this function will panic.

fn seek_prev_cp(&mut self)

Seeks the cursor to the beginning of the previous code point.

Panics

If the cursor is currently at the start of the string, then this function will panic.

Note

Where possible, you should prefer seek_prev.

fn seek_next_cp(&mut self)

Seeks the cursor to the beginning of the next code point.

Panics

If the cursor is currently at the end of the string, then this function will panic.

Note

Where possible, you should prefer seek_next.

fn prev(self) -> Option<(&'a Gc, StrCursor<'a>)>

Returns both the previous grapheme cluster and the cursor having seeked before it.

This may be more efficient than doing both operations individually.

fn prev_cp(self) -> Option<(char, StrCursor<'a>)>

Returns both the previous code point and the cursor having seeked before it.

This may be more efficient than doing both operations individually.

Note

Where possible, you should prefer prev.

fn next(self) -> Option<(&'a Gc, StrCursor<'a>)>

Returns both the next grapheme cluster and the cursor having seeked past it.

This may be more efficient than doing both operations individually.

fn next_cp(self) -> Option<(char, StrCursor<'a>)>

Returns both the next code point and the cursor having seeked past it.

This may be more efficient than doing both operations individually.

Note

Where possible, you should prefer next.

fn before(&self) -> Option<&'a Gc>

Returns the grapheme cluster immediately to the left of the cursor, or None is the cursor is at the start of the string.

fn after(&self) -> Option<&'a Gc>

Returns the grapheme cluster immediately to the right of the cursor, or None is the cursor is at the end of the string.

fn slice_before(&self) -> &'a str

Returns the contents of the string to the left of the cursor.

fn slice_after(&self) -> &'a str

Returns the contents of the string to the right of the cursor.

fn slice_between(&self, until: StrCursor<'a>) -> Option<&'a str>

Returns the contents of the string between this cursor and another cursor.

Returns None if the cursors are from different strings (even different subsets of the same string).

fn cp_before(&self) -> Option<char>

Returns the code point immediately to the left of the cursor, or None is the cursor is at the start of the string.

fn cp_after(&self) -> Option<char>

Returns the code point immediately to the right of the cursor, or None is the cursor is at the end of the string.

fn slice_all(&self) -> &'a str

Returns the entire string slice behind the cursor.

fn byte_pos(&self) -> usize

Returns the cursor's current position within the string as the number of UTF-8 code units from the beginning of the string.

Trait Implementations

impl<'a> Copy for StrCursor<'a>

impl<'a> Clone for StrCursor<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for StrCursor<'a>

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

Formats the value using the given formatter.

impl<'a> Eq for StrCursor<'a>

impl<'a> PartialEq for StrCursor<'a>

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

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

fn ne(&self, other: &StrCursor<'a>) -> bool

This method tests for !=.

impl<'a> PartialOrd for StrCursor<'a>

fn partial_cmp(&self, other: &StrCursor<'a>) -> 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> Hash for StrCursor<'a>

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.