Struct strcursor::StrCursor
[−]
[src]
pub struct StrCursor<'a> { /* 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>
[src]
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.
unsafe fn unsafe_seek_left(&mut self, bytes: usize)
Seeks exactly bytes
left, without performing any bounds or validity checks.
unsafe fn unsafe_seek_right(&mut self, bytes: usize)
Seeks exactly bytes
right, without performing any bounds or validity checks.
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> Copy for StrCursor<'a>
[src]
impl<'a> Clone for StrCursor<'a>
[src]
fn clone(&self) -> StrCursor<'a>
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl<'a> Debug for StrCursor<'a>
[src]
fn fmt(&self, fmt: &mut Formatter) -> Result<(), Error>
Formats the value using the given formatter.
impl<'a> Eq for StrCursor<'a>
[src]
impl<'a> PartialEq for StrCursor<'a>
[src]
fn eq(&self, other: &StrCursor<'a>) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &StrCursor<'a>) -> bool
This method tests for !=
.
impl<'a> PartialOrd for StrCursor<'a>
[src]
fn partial_cmp(&self, other: &StrCursor<'a>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more