Struct strcursor::StrCursor
[−]
[src]
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.
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 codepoint-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 codepoints. If you mis-align the cursor with respect to grapheme clusters, the behaviour of methods that deal with grapheme clusters is undefined.
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 grapheme cluster.
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 grapheme cluster.
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 before(&self) -> Option<&'a str>
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 str>
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 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 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.