Enum stam::ResultTextSelection

pub enum ResultTextSelection<'store> {
    Bound(ResultItem<'store, TextSelection>),
    Unbound(&'store AnnotationStore, &'store TextResource, TextSelection),
}

This structure holds a TextSelection, along with references to its TextResource and the AnnotationStore and provides a high-level API on it.

The text selection may either be bound, in which case it corresponds to a known/existing text selection and carries a handle, or unbound, in which case it is an arbitrary textselection.

Variants

Bound(ResultItem<'store, TextSelection>)

Unbound(&'store AnnotationStore, &'store TextResource, TextSelection)

Implementations

impl<'store> ResultTextSelection<'store>

pub fn inner(&self) -> &TextSelection

Return a reference to the inner textselection. This works in all cases but will have a limited lifetime. Use Self::as_ref() instead if you have bound item.

pub fn as_ref(&self) -> Option<&'store TextSelection>

Return a reference to the textselection in the store, with the appropriate lifetime. Only works on bound items. Use Self::inner() instead if you want something that always works.

pub fn as_resultitem(&self) -> Option<&ResultItem<'store, TextSelection>>

Return a reference to the textselection in the store. Only works on bound items.

pub fn begin(&self) -> usize

Return the begin position (unicode points)

pub fn end(&self) -> usize

Return the end position (non-inclusive) in unicode points

pub fn relative_begin( &self, container: &ResultTextSelection<'store> ) -> Option<usize>

Returns the begin cursor of this text selection in another. Returns None if they are not embedded. This also checks whether the textselections pertain to the same resource. Returns None otherwise.

pub fn relative_end( &self, container: &ResultTextSelection<'store> ) -> Option<usize>

Returns the end cursor (begin-aligned) of this text selection in another. Returns None if they are not embedded. This also checks whether the textselections pertain to the same resource. Returns None otherwise.

pub fn relative_offset( &self, container: &ResultTextSelection<'store>, offsetmode: OffsetMode ) -> Option<Offset>

Returns the offset of this text selection in another. Returns None if they are not embedded. This also checks whether the textselections pertain to the same resource. Returns None otherwise.

pub fn rootstore(&self) -> &'store AnnotationStore

Return the AnnotationStore this text selection references.

pub fn resource(&self) -> ResultItem<'store, TextResource>

Return the resource (ResultItem<TextResource>) this text selection references.

pub fn handle(&self) -> Option<TextSelectionHandle>

Returns the internal handle used by the TextSelection. If the TextSelection is unbound, this will return None by definition.

pub fn take(self) -> Result<TextSelection, StamError>

Takes ownership of the TextSelection, only works on unbound items, returns an error otherwise.

pub fn annotations( &self ) -> ResultIter<impl Iterator<Item = ResultItem<'store, Annotation>>>

Iterates over all annotations that are referenced by this TextSelection, if any. For unbound selections, this returns an empty iterator by definition.

pub fn annotations_len(&self) -> usize

Returns the number of annotations that reference this text selection For unbound selections, this is always 0.

pub fn related_text( &self, operator: TextSelectionOperator ) -> impl Iterator<Item = ResultTextSelection<'store>>

Applies a TextSelectionOperator to find all other text selections that are in a specific relation with the current one. Returns an iterator over the TextSelection instances. If you are interested in the annotations associated with the found text selections, then append .annotations().

pub fn positions<'a>( &'a self, mode: PositionMode ) -> Box<dyn Iterator<Item = &'a usize> + 'a>

Returns a sorted iterator over all absolute positions (begin aligned cursors) that overlap with this textselection and are in use in the underlying resource. By passing a PositionMode parameter you can specify whether you want only positions where a textselection begins, ends or both. This is a low-level function. Consider using .related_text(TextSelectionOperator::overlaps()) instead.

Trait Implementations

impl<'store> Clone for ResultTextSelection<'store>

fn clone(&self) -> ResultTextSelection<'store>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'store> Debug for ResultTextSelection<'store>

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

Formats the value using the given formatter.

impl<'store, 'slf> FindText<'store, 'slf> for ResultTextSelection<'store>

where 'store: 'slf,

fn find_text_regex<'regex>( &'slf self, expressions: &'regex [Regex], precompiledset: Option<&RegexSet>, allow_overlap: bool ) -> Result<FindRegexIter<'store, 'regex>, StamError>

Searches the text using one or more regular expressions, returns an iterator over TextSelections along with the matching expression, this is held by the FindRegexMatch struct.

Passing multiple regular expressions at once is more efficient than calling this function anew for each one. If capture groups are used in the regular expression, only those parts will be returned (the rest is context). If none are used, the entire expression is returned.

An offset can be specified to work on a sub-part rather than the entire text (like an existing TextSelection).

The allow_overlap parameter determines if the matching expressions are allowed to overlap. It you are doing some form of tokenisation, you also likely want this set to false. All of this only matters if you supply multiple regular expressions.

Results are returned in the exact order they are found in the text

fn find_text<'fragment>( &'slf self, fragment: &'fragment str ) -> FindTextIter<'store, 'fragment>

Searches for the specified text fragment. Returns an iterator to iterate over all matches in the text. The iterator returns TextSelection items.

For more complex and powerful searching use FindText::find_text_regex() instead

If you want to search only a subpart of the text, extract a TextSelection first and then run [self.find_text()] on that instead.

fn find_text_nocase(&'slf self, fragment: &str) -> FindNoCaseTextIter<'store>

Searches for the specified text fragment. Returns an iterator to iterate over all matches in the text. The iterator returns TextSelection items.

This search is case insensitive, use FindText::find_text() to search case sensitive. This variant is slightly less performant than the exact variant. For more complex and powerful searching use FindText::find_text_regex() instead

If you want to search only a subpart of the text, extract a TextSelection first with FindText::textselection() and then run FindText::find_text_nocase() on that instead.

fn textselection( &'slf self, offset: &Offset ) -> Result<ResultTextSelection<'store>, StamError>

Returns a TextSelection that corresponds to the offset WITHIN the textselection. This returns a TextSelection with absolute coordinates in the resource.

If the textselection is known (i.e. it has associated annotations), it will be returned as such with a handle (borrowed). If it doesn’t exist yet, a new one will be returned, and it won’t have a handle, nor will it be added to the store automatically.

The TextSelection is returned as in a far pointer (ResultTextSelection) that also contains reference to the underlying store (the TextResource).

fn split_text<'b>(&'slf self, delimiter: &'b str) -> SplitTextIter<'store, 'b>

Returns an iterator of TextSelection instances that represent partitions of the text given the specified delimiter. No text is modified.

fn find_text_sequence<'fragment, F>( &'slf self, fragments: &'fragment [&'fragment str], allow_skip_char: F, case_sensitive: bool ) -> Option<Vec<ResultTextSelection<'store>>>

where F: Fn(char) -> bool,

Searches for the multiple text fragment in sequence. Returns a vector with TextSelection instances wrapped as ResultTextSelection.

fn trim_text( &'slf self, chars: &[char] ) -> Result<ResultTextSelection<'store>, StamError>

Trims all occurrences of any character in chars from both the beginning and end of the text, returning a smaller TextSelection (as a fat pointer ResultTextSelection). No text is modified.

fn trim_text_with<F>( &'slf self, f: F ) -> Result<ResultTextSelection<'store>, StamError>

where F: Fn(char) -> bool,

Trims all occurrences of any character chars that pass the supplied function, from both the beginning and end of the text, returning a smaller TextSelection (as a fat pointer ResultTextSelection). No text is modified.

impl From<&ResultTextSelection<'_>> for Offset

fn from(textselection: &ResultTextSelection<'_>) -> Offset

Converts to this type from the input type.

impl<'store> From<ResultItem<'store, TextSelection>> for ResultTextSelection<'store>

fn from(textselection: ResultItem<'store, TextSelection>) -> Self

Converts to this type from the input type.

impl<'store> From<ResultTextSelection<'store>> for TextSelectionSet

fn from(textselection: ResultTextSelection<'store>) -> Self

Converts to this type from the input type.

impl<'store> FromIterator<ResultTextSelection<'store>> for TextSelectionSet

fn from_iter<T: IntoIterator<Item = ResultTextSelection<'store>>>( iter: T ) -> Self

Creates a value from an iterator.

impl<'store> PartialEq for ResultTextSelection<'store>

fn eq(&self, other: &Self) -> 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<'store> PartialOrd for ResultTextSelection<'store>

fn partial_cmp(&self, other: &Self) -> 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<'store, 'slf> Text<'store, 'slf> for ResultTextSelection<'store>

where 'store: 'slf,

fn text_by_offset(&'slf self, offset: &Offset) -> Result<&'store str, StamError>

Returns a string reference to a slice of text as specified by the offset

fn subslice_utf8_offset(&self, subslice: &str) -> Option<usize>

Finds the utf-8 byte position where the specified text subslice begins The returned offset is relative to the TextSelection

fn utf8byte(&self, abscursor: usize) -> Result<usize, StamError>

This converts a unicode point to utf-8 byte, all in relative offsets to this textselection

fn utf8byte_to_charpos(&self, bytecursor: usize) -> Result<usize, StamError>

This converts utf-8 byte to charpos, all in relative offsets to this textselection

fn text(&'slf self) -> &'store str

Returns a reference to the text

fn textlen(&self) -> usize

Returns the length of the text in unicode points For bytes, use Self::text().len() instead.

fn absolute_cursor(&self, cursor: usize) -> usize

Resolves a begin-aligned cursor to an absolute cursor (i.e. relative to the TextResource).

fn is_empty(&'slf self) -> bool

fn absolute_offset(&'slf self, offset: &Offset) -> Result<Offset, StamError>

Resolves a relative offset (relative to another TextSelection) to an absolute one (in terms of to the underlying TextResource)

fn beginaligned_cursor(&'slf self, cursor: &Cursor) -> Result<usize, StamError>

Resolves a cursor to a begin aligned cursor, resolving all relative end-aligned positions