Struct ResultItem 

pub struct ResultItem<'store, T>
where
    T: Storable,
{ /* private fields */ }

This is a smart pointer that encapsulates both the item and the store that owns it. It allows the item to have some more introspection as it knows who its immediate parent is. It is heavily used as a return type all throughout the higher-level API. Most API traits are implemented for a particular variant of this type.

For further documentation, look carefully for the implementation for T that you want information on:

• Annotation
• AnnotationData
• AnnotationDataSet
• DataKey
• TextResource
• TextSelection

Implementations

impl<'store> ResultItem<'store, Annotation>

This is the implementation of the high-level API for Annotation.

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

Returns an iterator over the resources that this annotation (by its target selector) references. This returns only resources that are targeted via a Selector::ResourceSelector and returns no duplicates even if a resource is referenced multiple times.

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

Returns an iterator over the resources that this annotation (by its target selector) references. This returns only resources that are targeted via a Selector::TextSelector and returns no duplicates even if a resource is referenced multiple times.

pub fn datasets( &self, ) -> ResultIter<impl Iterator<Item = ResultItem<'store, AnnotationDataSet>> + 'store>

Returns an iterator over the datasets that this annotation (by its target selector) references via a Selector::DataSetSelector. This returns no duplicates even if a dataset is referenced multiple times.

pub fn annotations_in_targets( &self, depth: AnnotationDepth, ) -> ResultIter<impl Iterator<Item = ResultItem<'store, Annotation>>>

Iterates over all the annotations this annotation targets (i.e. via a Selector::AnnotationSelector) Use Self::annotations() if you want to find the annotations that reference this one (the reverse operation).

Results will be in textual order unless depth is set to AnnotationDepth::Max or a Selector::DirectionalSelector is involved, then they are in the exact order as they were selected.

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

Returns an iterator over all annotations that reference this annotation, if any If you want to find the annotations this annotation targets, then use Self::annotations_in_targets() instead.

Results will be in chronological order and without duplicates, if you want results in textual order, add .iter().textual_order()

pub fn annotations_handles(&self) -> Annotations<'store>

Returns a borrowed collection of all the annotations that reference this annotation, if any If you want to find the annotations this annotation targets, then use Self::annotations_in_targets() instead.

Results will be in chronological order and without duplicates, if you want results in textual order, add .iter().textual_order()

pub fn textselections( &self, ) -> impl Iterator<Item = ResultTextSelection<'store>>

Iterate over all text selections this annotation references (i.e. via Selector::TextSelector) They are returned in textual order, except in case a Selector::DirectionalSelector is involved, then they are in the exact order as they were selected.

pub fn textselections_count(&self) -> usize

Returns the number of textselections under the annotation

pub fn text(&self) -> impl Iterator<Item = &'store str>

Iterates over all text slices this annotation refers to They are returned in textual order, or in case a Selector::DirectionalSelector is involved, in the exact order as they were selected.

pub fn text_simple(&self) -> Option<&'store str>

If this annotation refers to a single simple text slice, this returns it. If not contains no text or multiple text references, it returns None.

pub fn text_join(&self, delimiter: &str) -> String

Returns all underlying text for this annotation concatenated Shortcut for .textselections().text_join()

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

Returns the (single!) resource the annotation points to. Only works if this annotation targets using a Selector::TextSelector, Selector::ResourceSelector or Selector::AnnotationSelector, and not for complex selectors. Use Self::resources() if want to iterate over all resources instead. AnnotationSelectors are followed recursively if needed.

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

Get an iterator over all data (AnnotationData) for this annotation.

pub fn has_data(&self, data: &ResultItem<'_, AnnotationData>) -> bool

Tests if the annotation has certain data, returns a boolean. This will be a bit quicker than using .data().filter_one().

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

Returns an iterator over the AnnotationData that this annotation targets directly. This returns only resources that are targeted via a Selector::AnnotationDataSelector and returns no duplicates even if data is referenced multiple times.

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

Get an iterator over all keys (DataKey) used by data of this annotation. Shortcut for .data().keys().

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

Returns an iterator over the DataKeys that this annotation targets directly. This returns only resources that are targeted via a Selector::DataKeySelector and returns no duplicates even if a key is referenced multiple times.

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 text selected by this annotation. Returns an iterator over the crate::TextSelection instances, in textual order. (as ResultTextSelection).

This method is slightly different from .textselections().related_text(). This method will consider multiple textselections pertaining to this annotation as a single set, the other method treats each textselection separately.

pub fn textselectionset(&self) -> Option<ResultTextSelectionSet<'store>>

Returns the text this resources references as a single text selection set. This only works if the resource references text AND all text pertains to a single resource. If it can reference multiple resources, use textselectionsets() instead.

pub fn textselectionset_in( &self, resource: impl Request<TextResource>, ) -> Option<ResultTextSelectionSet<'store>>

Returns the text this resources references as a single text selection set. The text must pertain to the specified resource.

pub fn textselectionsets( &self, ) -> impl Iterator<Item = ResultTextSelectionSet<'store>>

Groups text selections targeting the same resource together in a TextSelectionSet.

pub fn test( &self, operator: &TextSelectionOperator, other: &ResultItem<'store, Annotation>, ) -> bool

Compares whether a particular spatial relation holds between two annotations

pub fn test_textselectionset( &self, operator: &TextSelectionOperator, other: &ResultTextSelectionSet<'_>, ) -> bool

Compares whether a particular spatial relation holds between this annotation and a textselection set.

pub fn test_textselection( &self, operator: &TextSelectionOperator, other: &ResultTextSelection<'_>, ) -> bool

Compares whether a particular spatial relation holds between this annotation and a textselection

pub fn substore(&self) -> Option<ResultItem<'store, AnnotationSubStore>>

Returns the substore this annotation is a part of (if any)

impl<'store> ResultItem<'store, AnnotationData>

This is the implementation of the high-level API for AnnotationData.

pub fn set(&self) -> ResultItem<'store, AnnotationDataSet>

Return a reference to the dataset that holds this data

pub fn value(&self) -> &'store DataValue

Return a reference to the data value

pub fn key(&self) -> ResultItem<'store, DataKey>

Return a reference to the key for this data

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

Returns an iterator over all annotations (Annotation) that makes use of this data. The iterator returns the annotations as ResultItem<Annotation>. Especially useful in combination with a call to [ResultItem<AnnotationDataSet>.find_data()] or [AnnotationDataSet.annotationdata()] first.

pub fn annotations_len(&self) -> usize

Returns the number of annotations (Annotation) that make use of this data.

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

Returns an iterator over all annotations about this data, i.e. Annotations with an AnnotationDataSelector. Such annotations can be considered metadata.

pub fn test( &self, key: impl Request<DataKey>, operator: &DataOperator<'_>, ) -> bool

pub fn resources_as_metadata( &self, ) -> <BTreeSet<ResultItem<'store, TextResource>> as IntoIterator>::IntoIter

Returns an set of all text resources that make use of this data via annotations via a ResourceSelector (i.e. as metadata)

pub fn resources( &self, ) -> <BTreeSet<ResultItem<'store, TextResource>> as IntoIterator>::IntoIter

Returns an iterator over all text resources that make use of this data via annotations via a TextSelector (i.e. on text)

pub fn datasets( &self, ) -> <BTreeSet<ResultItem<'store, AnnotationDataSet>> as IntoIterator>::IntoIter

Returns an iterator over all data sets that annotations using this data reference via a DataSetSelector (i.e. as metadata)

pub fn to_json_string(&self) -> Result<String, StamError>

pub fn to_json_value(&self) -> Result<Value, StamError>

impl<'store> ResultItem<'store, AnnotationDataSet>

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

Returns an iterator over all data in this set.

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

Returns an iterator over all keys in this set

pub fn key( &self, key: impl Request<DataKey>, ) -> Option<ResultItem<'store, DataKey>>

Retrieve a DataKey in this set

pub fn annotationdata( &self, annotationdata: impl Request<AnnotationData>, ) -> Option<ResultItem<'store, AnnotationData>>

Retrieve a single AnnotationData in this set

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

Returns an iterator over annotations that directly point at the dataset, i.e. are metadata for it (via a DataSetSelector).

pub fn find_data<'q>( &self, key: impl Request<DataKey>, value: DataOperator<'q>, ) -> Box<dyn Iterator<Item = ResultItem<'store, AnnotationData>> + 'store>

where 'q: 'store,

Finds the AnnotationData in the annotation dataset. Returns an iterator over all matches. If you’re not interested in returning the results but merely testing their presence, use Self::test_data() instead.

If you pass an empty string literal or boolean to key, all keys will be searched.

If you already have a ResultItem<DataKey> , use [ResultItem<DataKey>.find_data()] instead, it’ll be much more efficient.

Value is a DataOperator, it is not wrapped in an Option but can be set to DataOperator::Any to return all values.

Example

//in this store we have a single annotation, and single annotation data with key 'part-of-speech' and value 'noun':
let dataset = store.dataset("mydataset").or_fail()?;
for annotationdata in dataset.find_data("part-of-speech", DataOperator::Equals("noun".into())) {
    assert_eq!(annotationdata.id(), Some("D1"));
    assert_eq!(annotationdata.value(), "noun");
}

pub fn test_data<'a>( &self, key: impl Request<DataKey>, value: DataOperator<'a>, ) -> bool

Tests if the dataset has certain data, returns a boolean. If you want to actually retrieve the data, use find_data() instead.

If you pass an empty string literal or boolean to key, all keys will be searched. Value is a DataOperator, it can be set set to DataOperator::Any to return all values.

pub fn test(&self, other: impl Request<AnnotationDataSet>) -> bool

Tests whether two AnnotationDataSets are the same

pub fn substores<'a>( &'a self, ) -> ResultIter<impl Iterator<Item = ResultItem<'a, AnnotationSubStore>>>

Returns an iterator over all substores (AnnotationSubStore instances) this dataset is a part of.

impl<'store> ResultItem<'store, DataKey>

This is the implementation of the high-level API for DataKey.

pub fn set(&self) -> ResultItem<'store, AnnotationDataSet>

Returns a reference to the dataset that holds this key

pub fn as_str(&self) -> &'store str

Returns the public identifier that identifies the key

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

Returns an iterator over all data (crate::AnnotationData) that makes use of this key. Use methods on this iterator like [DataIter.filter_value()] to further constrain the results.

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

Returns an iterator over all annotations (crate::Annotation) that make use of this key.

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

Returns an iterator over all annotations about this datakey, i.e. Annotations with a DataKeySelector. Such annotations can be considered metadata.

pub fn annotations_count(&self) -> usize

Returns the number of annotations that make use of this key. Note: this method has suffix _count instead of _len because it is not O(1) but does actual counting (O(n) at worst). (This function internally allocates a temporary buffer to ensure no duplicates are returned)

pub fn test(&self, other: impl Request<DataKey>) -> bool

Tests whether two DataKeys are the same

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

Returns a set of all text resources (crate::TextResource) that make use of this key as metadata (via annotations with a ResourceSelector)

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

Returns a set of all text resources (crate::TextResource) that make use of this key via annotations via a ResourceSelector (i.e. as metadata)

pub fn datasets(&self) -> BTreeSet<ResultItem<'store, AnnotationDataSet>>

Returns a set of all data sets (crate::AnnotationDataSet) that annotations using this key reference via a DataSetSelector (i.e. metadata)

impl<'store> ResultItem<'store, TextResource>

This is the implementation of the high-level API for TextResource.

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

Returns an iterator over all annotations about this resource as a whole, i.e. Annotations with a ResourceSelector. Such annotations can be considered metadata.

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

Returns an iterator over all annotations about any text in this resource i.e. Annotations with a TextSelector.

pub fn textselections( &self, ) -> impl DoubleEndedIterator<Item = ResultTextSelection<'store>>

Returns an iterator over all text selections that are marked in this resource (i.e. there are one or more annotations on it). They are returned in textual order, but this does not come with any significant performance overhead. If you want an unsorted version use [self.as_ref().textselections_unsorted()] instead. Note: This is a double-ended iterator that can be traversed in both directions.

pub fn textselection_by_handle( &self, handle: TextSelectionHandle, ) -> Result<ResultTextSelection<'store>, StamError>

pub fn to_textselection(self) -> ResultTextSelection<'store>

Get a text selection pointing to the whole resource, you can also call this implicitly via the From trait (resource.into()).

pub fn textselections_in_range( &self, begin: usize, end: usize, ) -> impl DoubleEndedIterator<Item = ResultTextSelection<'store>>

Returns a sorted double-ended iterator over a range of all textselections and returns all textselections that either start or end in this range (depending on the direction you’re iterating in)

pub fn textselections_len(&self) -> usize

Returns the number of textselections that are marked in this resource (i.e. there are one or more annotations on it).

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

Find textselections by applying a text selection operator (TextSelectionOperator) to a one or more querying textselections. Returns an iterator over all matching text selections in the resource.

pub fn annotations_by_metadata_about( &self, data: ResultItem<'store, AnnotationData>, ) -> impl Iterator<Item = ResultItem<'store, Annotation>> + 'store

Search for annotations about this resource, satisfying certain exact data that is already known. For a higher-level variant, see find_data_about, this method is more efficient. Both the matching data as well as the matching annotation will be returned in an iterator.

pub fn has_metadata_about( &self, data: ResultItem<'store, AnnotationData>, ) -> bool

Tests if the resource has certain data in annotations that reference this textselection, returns a boolean. If you don’t have a data instance yet, use test_data_about() instead. This method is much more efficient than test_data_about().

pub fn segmentation(&self) -> SegmentationIter<'store>

Iterator covering the full text of the resource as a sequence of minimum-length non-overlapping TextSelections, in textual order

pub fn segmentation_in_range( &self, begin: usize, end: usize, ) -> SegmentationIter<'store>

Iterator covering a range of text of the resource as a sequence of minimum-length non-overlapping TextSelections, in textual order

pub fn substores<'a>( &'a self, ) -> ResultIter<impl Iterator<Item = ResultItem<'a, AnnotationSubStore>>>

Returns an iterator over all substores (AnnotationSubStore instances) this resource is a part of.

impl<'store> ResultItem<'store, AnnotationSubStore>

This is the implementation of the high-level API for AnnotationSubStore.

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

Returns an iterator over all annotations in this substore. Results will be in chronological order

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

Returns an iterator over all resources in this substore. Results will be in chronological order

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

Returns an iterator over all datasets in this substore. Results will be in chronological order

pub fn substores<'a>( &'a self, ) -> ResultIter<impl Iterator<Item = ResultItem<'a, AnnotationSubStore>>>

Returns an iterator over all substores (AnnotationSubStore instances) in under this substore. The resulting iterator yields items as a fat pointer ResultItem<AnnotationSubStore>), which exposes the high-level API. Note that each substore may itself consist of further substores!

impl<'store> ResultItem<'store, TextSelection>

This is the implementation of the high-level API for TextSelection, though most of it is more commonly used via ResultTextSelection.

pub fn as_resulttextselection(self) -> ResultTextSelection<'store>

Returns the higher level structure

pub fn begin(&self) -> usize

Return the begin position (unicode points)

pub fn end(&self) -> usize

Return the end position (unicode points)

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

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

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

Iterates over all annotations that reference this TextSelection

pub fn annotations_len(&self) -> usize

Returns the number of annotations that reference this text selection This is more performant than doing self.annotations().count().

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. (as ResultTextSelection). If you are interested in the annotations associated with the found text selections, append annotations().

impl<'store> ResultItem<'store, Annotation>

pub fn to_webannotation(&self, config: &WebAnnoConfig) -> String

Outputs the annotation as a W3C Web Annotation, the output will be JSON-LD on a single line without pretty formatting.

impl<'store, T> ResultItem<'store, T>

where T: Storable,

pub fn store(&self) -> &'store T::StoreType

Get the store this item is a direct member of

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

Get the underlying AnnotationStore

pub fn as_ref(&self) -> &'store T

Returns the contained reference with the original lifetime

pub fn handle(&self) -> T::HandleType

Get the handle (internal identifier) for the contained item

pub fn id(&self) -> Option<&'store str>

Get the public identifier for the contained item

impl<'store> ResultItem<'store, AnnotationSubStore>

pub fn save(&self) -> Result<(), StamError>

impl<'store> ResultItem<'store, Annotation>

pub fn text_checksum(&self, delimiter: &str) -> Option<String>

Returns (computes) the SHA-1 checksum of the text of this annotation (if any, empty vec otherwise) Note that this is cryptographically insecure! (but fast)

pub fn text_validation_delimiter(&self) -> Option<&'store str>

Returns the text delimiter used for text validation (if any)

pub fn validation_checksum(&self) -> Option<&'store str>

Get the text validation checksum associated with this annotation (if any) To compute the actual checksum, use [text_checksum()]

pub fn validation_text(&self) -> Option<&'store str>

Returns the associated validation text, if any

pub fn validate_text(&self) -> Option<bool>

Tests if the annotation’s target text is still valid Returns None if there is no validation information in the annotation at all!

Trait Implementations

impl<'store, T> Clone for ResultItem<'store, T>

where T: Storable + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'store, T> Debug for ResultItem<'store, T>

where T: Storable,

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

Formats the value using the given formatter.

impl<'store, T> Eq for ResultItem<'store, T>

where T: Storable,

impl<'store, 'slf> FindText<'store, 'slf> for ResultItem<'store, TextResource>

where 'store: 'slf,

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

Returns a TextSelection that corresponds to the offset. If the TextSelection exists, the existing one will be returned. 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 in a fat pointer (ResultTextSelection) that also contains reference to the underlying store.

fn find_text_regex<'regex>( &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.

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>( &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.

This search is case sensitive, use FindText::find_text_nocase() to search case insensitive. 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() on that instead.

fn find_text_nocase(&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 split_text<'b>(&self, delimiter: &'b str) -> SplitTextIter<'store, 'b>

Splits the text of this resource given a delimiter, the resulting iterator yields TextSelection items (as ResultTextSelection).

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<'store, 'slf> FindText<'store, 'slf> for ResultItem<'store, TextSelection>

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 FindText::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 (ResultItem) 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<&ResultItem<'_, TextSelection>> for Offset

fn from(textselection: &ResultItem<'_, TextSelection>) -> Offset

Converts to this type from the input type.

impl<'a, T> From<&ResultItem<'a, T>> for BuildItem<'a, T>

where T: Storable,

fn from(result: &ResultItem<'a, T>) -> Self

Converts to this type from the input type.

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

fn from(resource: ResultItem<'store, TextResource>) -> Self

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<ResultItem<'store, TextSelection>> for TextSelectionSet

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

Converts to this type from the input type.

impl<'store> FromIterator<ResultItem<'store, TextSelection>> for TextSelectionSet

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

Creates a value from an iterator.

impl<'store, T> Hash for ResultItem<'store, T>

where T: Storable,

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

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<'store> IRI<'store> for ResultItem<'store, Annotation>

fn iri(&self, default_prefix: &str) -> Option<Cow<'store, str>>

Return the identifier as an IRI, suitable to identify RDF resources This will apply some transformations if there are invalid characters in the ID A default prefix will be prepended if the identifier was not an IRI yet.

impl<'store> IRI<'store> for ResultItem<'store, AnnotationDataSet>

fn iri(&self, default_prefix: &str) -> Option<Cow<'store, str>>

Return the identifier as an IRI, suitable to identify RDF resources This will apply some transformations if there are invalid characters in the ID A default prefix will be prepended if the identifier was not an IRI yet.

impl<'store> IRI<'store> for ResultItem<'store, DataKey>

fn iri(&self, default_set_prefix: &str) -> Option<Cow<'store, str>>

Return the identifier as an IRI, suitable to identify RDF resources This will apply some transformations if there are invalid characters in the ID A default prefix will be prepended if the identifier was not an IRI yet.

impl<'store> IRI<'store> for ResultItem<'store, TextResource>

fn iri(&self, default_prefix: &str) -> Option<Cow<'store, str>>

Return the identifier as an IRI, suitable to identify RDF resources This will apply some transformations if there are invalid characters in the ID A default prefix will be prepended if the identifier was not an IRI yet.

impl<'store, T> Ord for ResultItem<'store, T>

where T: Storable,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'store, T> PartialEq for ResultItem<'store, T>

where T: Storable,

fn eq(&self, other: &Self) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl<'store, T> PartialOrd for ResultItem<'store, T>

where T: Storable,

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

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, T> Request<T> for &ResultItem<'a, T>

where T: Storable,

fn to_handle<'store, S>(&self, _store: &'store S) -> Option<T::HandleType>

where S: StoreFor<T>,

Returns the handle for this item, looking it up in the store

fn requested_id(&self) -> Option<&str>

If this type encapsulates an Id, this returns it (borrowed)

fn requested_id_owned(self) -> Option<String>

If this type encapsulates an Id, this returns it (oened)

fn requested_handle(&self) -> Option<T::HandleType>

If this type encapsulates a handle, this returns it

fn any(&self) -> bool

Represents a request for any value in certain contexts

impl<'a, T> Request<T> for ResultItem<'a, T>

where T: Storable,

fn to_handle<'store, S>(&self, _store: &'store S) -> Option<T::HandleType>

where S: StoreFor<T>,

Returns the handle for this item, looking it up in the store

fn requested_id(&self) -> Option<&str>

If this type encapsulates an Id, this returns it (borrowed)

fn requested_id_owned(self) -> Option<String>

If this type encapsulates an Id, this returns it (oened)

fn requested_handle(&self) -> Option<T::HandleType>

If this type encapsulates a handle, this returns it

fn any(&self) -> bool

Represents a request for any value in certain contexts

impl<'a> Serialize for ResultItem<'a, Annotation>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> Serialize for ResultItem<'a, AnnotationData>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'store> Serialize for ResultItem<'store, AnnotationSubStore>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'store, 'slf> Text<'store, 'slf> for ResultItem<'store, TextResource>

where 'store: 'slf,

this implementation mostly defers directly to the wrapped item, documentation is found on the trait and not repeated here

fn textlen(&self) -> usize

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

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

Returns a reference to the text

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

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

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

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

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

Converts a unicode character position to a UTF-8 byte position

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

Converts a UTF-8 byte position into a unicode position

fn subslice_utf8_offset(&'slf 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 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

impl<'store, 'slf> Text<'store, 'slf> for ResultItem<'store, TextSelection>

where 'store: 'slf,

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

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

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 subslice_utf8_offset(&'slf 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 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

impl<'store> ToJson for ResultItem<'store, AnnotationSubStore>

fn to_json_writer<W>(&self, writer: W, compact: bool) -> Result<(), StamError>

where W: Write,

Writes a serialisation (choose a dataformat) to any writer Lower-level function

fn to_json_file(&self, filename: &str, config: &Config) -> Result<(), StamError>

Writes this structure to a file The actual dataformat can be set via config, the default is STAM JSON.

fn to_json_string(&self, config: &Config) -> Result<String, StamError>

Serializes this structure to one string. The actual dataformat can be set via config, the default is STAM JSON. If config not not specified, an attempt to fetch the AnnotationStore’s initial config is made

fn to_json_value(&self) -> Result<Value, StamError>

Serializes this structure to a JSON value If config not not specified, an attempt to fetch the AnnotationStore’s initial config is made

impl<'store> Translatable<'store> for ResultItem<'store, Annotation>

fn translate( &self, via: &TranslationPivot<'store>, config: TranslateConfig, ) -> Result<Vec<AnnotationBuilder<'static>>, StamError>

The translate function maps an annotation, textselection, or textselection set from one coordinate system to another. These mappings are defined in annotations called translations and are documented here: https://github.com/annotation/stam/blob/master/extensions/stam-translate/README.md translations link identical textual parts across resources, any annotations within the bounds of such a mapping can then be translated using this function to the other coordinate system.

impl<'store> Transposable<'store> for ResultItem<'store, Annotation>

fn transpose( &self, via: &TranspositionPivot<'store>, config: TransposeConfig, ) -> Result<Vec<AnnotationBuilder<'static>>, StamError>

The transpose function maps an annotation, textselection, or textselection set from one coordinate system to another. These mappings are defined in annotations called transpositions and are documented here: https://github.com/annotation/stam/blob/master/extensions/stam-transpose/README.md Transpositions link identical textual parts across resources, any annotations within the bounds of such a mapping can then be transposed using this function to the other coordinate system.

impl<'store> TryFrom<&ResultItem<'store, Annotation>> for ResultTextSelectionSet<'store>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from( annotation: &ResultItem<'store, Annotation>, ) -> Result<Self, Self::Error>

Performs the conversion.

impl<'store> TryFrom<&ResultItem<'store, Annotation>> for TranslationPivot<'store>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from( annotation: &ResultItem<'store, Annotation>, ) -> Result<Self, Self::Error>

Performs the conversion.

impl<'store> TryFrom<&ResultItem<'store, Annotation>> for TranspositionPivot<'store>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from( annotation: &ResultItem<'store, Annotation>, ) -> Result<Self, Self::Error>

Performs the conversion.

impl<'store> TryFrom<ResultItem<'store, Annotation>> for TranslationPivot<'store>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from( annotation: ResultItem<'store, Annotation>, ) -> Result<Self, Self::Error>

Performs the conversion.

impl<'store> TryFrom<ResultItem<'store, Annotation>> for TranspositionPivot<'store>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from( annotation: ResultItem<'store, Annotation>, ) -> Result<Self, Self::Error>

Performs the conversion.

impl<'store, T> TypeInfo for ResultItem<'store, T>

where T: Storable + TypeInfo,

fn typeinfo() -> Type

Return the type (introspection).

fn temp_id_prefix() -> &'static str

Return the prefix for temporary identifiers of this type