Enum stam::WrappedItem

pub enum WrappedItem<'store, T>where
    T: Storable,{
    Borrowed {
        item: &'store T,
        store: &'store T::StoreType,
    },
    Owned {
        item: T,
        store: &'store T::StoreType,
    },
}

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 used for example in serialization.

Variants

Borrowed

Fields

item: &'store T

store: &'store T::StoreType

Owned

Fields

item: T

store: &'store T::StoreType

Implementations

impl<'store, 'slf> WrappedItem<'store, Annotation>

pub fn data( &'slf self ) -> impl Iterator<Item = WrappedItem<'store, AnnotationData>> + 'slf

Iterate over the annotation data, returns WrappedItem<AnnotationData>.

pub fn resources(&'slf self) -> TargetIter<'store, TextResource>

Iterates over the resources this annotation points to

pub fn annotations( &'slf self, recursive: bool, track_ancestors: bool ) -> TargetIter<'store, Annotation>

Iterates over all the annotations this annotation points to directly (i.e. via a [Selector::AnnotationSelector']) Use [Self.annotations_reverse()’] if you want to find the annotations this resource is pointed by.

pub fn annotations_reverse( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + 'slf>

Iterates over all the annotations that reference this annotation, if any

pub fn annotationsets(&'slf self) -> TargetIter<'store, AnnotationDataSet>

Iterates over the annotation data sets this annotation points to (only the ones it points to directly using DataSetSelector, i.e. as metadata)

pub fn textselections( &'slf self ) -> impl Iterator<Item = WrappedItem<'store, TextSelection>> + 'slf

Iterate over all resources with text selections this annotation refers to (i.e. via Selector::TextSelector)

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

Iterates over all text slices this annotation refers to

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

Returns the resource the annotation points to. Only works for TextSelector, ResourceSelector and AnnotationSelector, and not for complex selectors. Returns a WrongSelectorType error if the annotation does not point at any resource.

pub fn find_data<'a>( &'slf self, set: Option<Item<'_, AnnotationDataSet>>, key: Option<Item<'_, DataKey>>, value: DataOperator<'a> ) -> Option<impl Iterator<Item = WrappedItem<'store, AnnotationData>> + 'slf>where 'a: 'slf,

Finds the [AnnotationData'] in the annotation. Returns an iterator over all matches. Provide setandkey as Options, if set toNone, all sets and keys will be searched. Value is a DataOperator, it is not wrapped in an Option but can be set to DataOperator::Anyto return all values. Note: If you pass akeyyou must also passset`, otherwise the key will be ignored.

impl<'store, 'slf> WrappedItem<'store, AnnotationData>

pub fn set(&'slf self) -> &'store AnnotationDataSet

Return a reference to the AnnotationDataSet that holds this data (and its key)

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

pub fn annotations( &'slf self, annotationstore: &'store AnnotationStore ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + 'slf>

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

pub fn annotations_len( &'slf self, annotationstore: &'store AnnotationStore ) -> usize

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

impl<'store, 'slf> WrappedItem<'store, AnnotationDataSet>

pub fn data_by_value( &self, key: Item<'_, DataKey>, value: &DataValue ) -> Option<WrappedItem<'store, AnnotationData>>

Returns [AnnotationData'] in the annotation dataset that matches they key and value. Returns a single match, use Self::find_data()` for a more extensive search.

pub fn find_data<'a>( &'slf self, key: Option<Item<'_, DataKey>>, value: DataOperator<'a> ) -> Option<impl Iterator<Item = WrappedItem<'store, AnnotationData>> + '_>where 'slf: 'store, 'a: 'slf,

Finds the [AnnotationData'] in the annotation dataset. Returns an iterator over all matches. Provide key as an Options, if set toNone, all keys will be searched. Value is a DataOperator, it is not wrapped in an Option but can be set to DataOperator::Any` to return all values.

pub fn annotations( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + '_>

Returns all annotations that use this dataset. Use [Self.annotations_metadata()] instead if you are looking for annotations that reference the dataset as a whole via a DataSetSelector. These are also included here, though.

pub fn annotations_metadata( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + '_>

This only returns annotations that directly point at the resource, i.e. are metadata for it. It does not include annotations that point at a text in the resource, use [Self.annotations_by_resource()] instead for those.

impl<'store, 'slf> WrappedItem<'store, DataKey>

pub fn set(&'slf self) -> &'store AnnotationDataSet

Shortcut to return a reference to the dataset

pub fn data( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, AnnotationData>> + 'slf>

Returns an iterator over all data (AnnotationData) that makes use of this key. The iterator returns the data as WrappedItem<AnnotationData>.

pub fn annotations( &'slf self, annotationstore: &'store AnnotationStore ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + 'slf>

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

pub fn annotations_count( &'slf self, annotationstore: &'store AnnotationStore ) -> 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).

impl<'store, 'slf> WrappedItem<'store, TextResource>

pub fn annotations( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + '_>

Returns all annotations that reference any text selection in the resource. Use [Self.annotations_metadata()] instead if you are looking for annotations that reference the resource as is via a ResourceSelector. These are NOT include here.

pub fn annotations_metadata( &'slf self ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + '_>

This only returns annotations that directly point at the resource, i.e. are metadata for it. It does not include annotations that point at a text in the resource, use [Self.annotations_by_resource()] instead for those.

impl<'store, T> WrappedItem<'store, T>where T: Storable,

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

pub fn unwrap<'slf>(&'slf self) -> &'store T

Returns the contained reference with the original lifetime, unlike [Self.deref()]! This only works on Borrowed types though! Will panic on owned types! Using this is usually safe except when dealing with [TextSelection].

If strict lifetime preservation is not an issue, you can get away with just using [’Self::deref()`], which is implicit (deref coercion).

pub fn unwrap_owned<'slf>(self) -> T

pub fn expect<'slf>(&'slf self, msg: &str) -> &'store T

Returns the contained reference with the original lifetime, unlike [Self.deref()]! This only works on Borrowed types though! Will panic on owned types!

pub fn is_borrowed(&self) -> bool

pub fn is_owned(&self) -> bool

impl<'store, 'slf> WrappedItem<'store, TextSelection>

pub fn resource(&'slf self) -> &'store TextResource

pub fn annotations( &'slf self, annotationstore: &'store AnnotationStore ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>>>

Iterates over all annotations that are referenced by this TextSelection, if any. Note that you need to explicitly specify the AnnotationStore for this method.

pub fn annotations_len( &'slf self, annotationstore: &'store AnnotationStore ) -> usize

Returns the number of annotations that reference this text selection

pub fn to_ref(&self) -> Option<WrappedItem<'store, TextSelection>>

Converts the TextSelection to a reference to an item in the store, if not possible or already a reference, None is returned.

pub fn find_textselections( &'slf self, operator: TextSelectionOperator ) -> impl Iterator<Item = WrappedItem<'store, TextSelection>>

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 WrappedItem<TextSelection>). If you are interested in the annotations associated with the found text selections, then use [Self.find_annotations()] instead.

pub fn find_annotations( &'slf self, operator: TextSelectionOperator, annotationstore: &'store AnnotationStore ) -> impl Iterator<Item = WrappedItem<'store, Annotation>>

Applies a TextSelectionOperator to find annotations referencing other text selections that are in a specific relation with the current one. Returns an iterator over the TextSelection instances. (as WrappedItem<TextSelection>). If you are interested in the text selections only, use [Self.find_textselections()] instead.

impl<'store, 'slf> WrappedItem<'store, Annotation>

pub fn find_textselections( &'slf self, operator: TextSelectionOperator ) -> Option<impl Iterator<Item = WrappedItem<'store, TextSelection>>>

Applies a TextSelectionOperator to find all other text selections that are in a specific relation with the text relations pertaining to the annotations. Returns an iterator over the TextSelection instances. (as WrappedItem<TextSelection>). If you are interested in the annotations associated with the found text selections, then use [Self.find_annotations()] instead.

pub fn find_annotations( &'slf self, operator: TextSelectionOperator ) -> Option<impl Iterator<Item = WrappedItem<'store, Annotation>> + 'slf>

Applies a TextSelectionOperator to find annotations referencing other text selections that are in a specific relation with the text selections of the current one. Returns an iterator over the TextSelection instances. (as WrappedItem<TextSelection>). If you are interested in the text selections only, use [Self.find_textselections()] instead.

Trait Implementations

impl<'store, T> Clone for WrappedItem<'store, T>where T: Storable + Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'store, T> Debug for WrappedItem<'store, T>where T: Storable + Debug, T::StoreType: Debug,

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

Formats the value using the given formatter.

impl<'store, T> Deref for WrappedItem<'store, T>where T: Storable,

fn deref(&self) -> &Self::Target

This may be a cause for lifetime problems, as it returns a reference with the lifetime of WrappedItem rather than the contained item. Use Self::unwrap() instead in those cases.

type Target = T

The resulting type after dereferencing.

impl From<&WrappedItem<'_, TextSelection>> for Offset

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

Converts to this type from the input type.

impl<'store> From<WrappedItem<'store, TextSelection>> for TextSelectionSet

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

Converts to this type from the input type.

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

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

Creates a value from an iterator.

impl<'store, T> PartialEq<&T> for WrappedItem<'store, T>where T: Storable,

fn eq(&self, other: &&T) -> 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<'a> Serialize for WrappedItem<'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 WrappedItem<'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, 'slf> Text<'store, 'slf> for WrappedItem<'store, TextSelection>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 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 [Self.find_text_regex()] instead

If you want to search only a subpart of the text, extract a [’TextSelection] first and then run 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 [Self.find_text()] to search case sensitive. This variant is slightly less performant than the exact variant. For more complex and powerful searching use [Self.find_text_regex()] instead

If you want to search only a subpart of the text, extract a [’TextSelection] first with [Self.textselection()] and then run find_text_nocase()` on that instead.

fn textselection( &'slf self, offset: &Offset ) -> Result<WrappedItem<'store, TextSelection>, 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 (WrappedItem) that also contains reference to the underlying store (the TextResource).

Use [Self::has_textselection()] instead if you want to limit to existing text selections (i.e. those pertaining to annotations) only.

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 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 absolute_cursor(&self, cursor: usize) -> usize

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

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

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

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

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

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

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

fn absolute_offset(&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)