Struct StrCursor

pub struct StrCursor<'a> { /* private fields */ }

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

Implementations

impl<'a> StrCursor<'a>

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

Create a new cursor at the start of s.

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

Create a new cursor past at the end of s.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

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

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

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

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

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

pub 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.

pub 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.

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

Returns the entire string slice behind the cursor.

pub 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.

pub unsafe fn unsafe_seek_left(&mut self, bytes: usize)

Seeks exactly bytes left, without performing any bounds or validity checks.

pub unsafe fn unsafe_seek_right(&mut self, bytes: usize)

Seeks exactly bytes right, without performing any bounds or validity checks.

pub unsafe fn unsafe_set_at(&mut self, s: &'a str)

Seeks to the start of s, without performing any bounds or validity checks.

Trait Implementations

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> Hash for StrCursor<'a>

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<'a> PartialEq for StrCursor<'a>

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

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

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

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

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

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<'a> Copy for StrCursor<'a>

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