Enum stam::Selector

pub enum Selector {
    TextSelector(TextResourceHandle, TextSelectionHandle, OffsetMode),
    AnnotationSelector(AnnotationHandle, Option<(TextResourceHandle, TextSelectionHandle, OffsetMode)>),
    ResourceSelector(TextResourceHandle),
    DataSetSelector(AnnotationDataSetHandle),
    MultiSelector(Vec<Selector>),
    CompositeSelector(Vec<Selector>),
    DirectionalSelector(Vec<Selector>),
    DataKeySelector(AnnotationDataSetHandle, DataKeyHandle),
    AnnotationDataSelector(AnnotationDataSetHandle, AnnotationDataHandle),
    RangedTextSelector {
        resource: TextResourceHandle,
        begin: TextSelectionHandle,
        end: TextSelectionHandle,
    },
    RangedAnnotationSelector {
        begin: AnnotationHandle,
        end: AnnotationHandle,
        with_text: bool,
    },
}

A Selector identifies the target of an annotation and the part of the target that the annotation applies to. Selectors can be considered the labelled edges of the graph model, tying all nodes together. There are multiple types of selectors, all captured in this enum.

You usually do not instantiate these directly but via SelectorBuilder. In searching, you also don’t need direct access to this structure as the various search methods on AnnotationStore will resolve the selectors transparently.

Variants

TextSelector(TextResourceHandle, TextSelectionHandle, OffsetMode)

Refers to the TextResource and a TextSelection within

AnnotationSelector(AnnotationHandle, Option<(TextResourceHandle, TextSelectionHandle, OffsetMode)>)

Refers to an Annotation (as owned by the AnnotationStore) and optionally a relative text selection offset in it

ResourceSelector(TextResourceHandle)

Refers to a TextResource as a whole (as opposed to a text fragment inside it), as owned by an AnnotationStore. Annotations using this selector can be considered metadata of a text

DataSetSelector(AnnotationDataSetHandle)

Refers to an crate::AnnotationDataSet as owned by an AnnotationStore Annotations using this selector can be considered metadata.

MultiSelector(Vec<Selector>)

A selector that combines selectors, where the annotation applies to each target individually. without any relation between the different targets. Leaving one out or adding one MUST NOT affect the interpretation of any of the others nor of the whole. This is a way to express multiple annotations as one, a more condensed representation. This selector SHOULD be used sparingly in your modelling, as it is generally RECOMMENDED to simply use multiple Annotation instances instead. In STAM, even with multiple annotations, you benefit from the fact that multiple annotations may share the same crate::AnnotationData, and can therefore easily retrieve all annotations that share particular data.

CompositeSelector(Vec<Selector>)

A selector that consists of multiple other selectors, used to select more complex targets that transcend the idea of a single simple selection. This MUST be interpreted as the annotation applying equally to the conjunction as a whole, its parts being inter-dependent and for any of them it goes that they MUST NOT be omitted for the annotation to make sense. The interpretation of the whole relies on all its parts. Note that the order of the selectors is not significant (use a Self::DirectionalSelector instead if they are). When there is no dependency relation between the selectors, you MUST simply use multiple Annotation instances or a Self::MultiSelector instead. When grouping things into a set, do use this Self::CompositeSelector, as the set as a whole is considered a composite entity.

DirectionalSelector(Vec<Selector>)

Combines selectors and expresseds a direction between two or more selectors in the exact order specified (from -> to)

DataKeySelector(AnnotationDataSetHandle, DataKeyHandle)

Refers to a DataKey to annotate. Annotations using this selector are considered metadata of a key

AnnotationDataSelector(AnnotationDataSetHandle, AnnotationDataHandle)

Refers to a AnnotationData to annotate. Annotations using this selector can be considered metadata on specific data, it is fairly rare.

RangedTextSelector

Internal ranged selector, used as subselector for MultiSelector/CompositeSelector/DirectionalSelector

Fields

resource: TextResourceHandle

begin: TextSelectionHandle

end: TextSelectionHandle

RangedAnnotationSelector

Internal ranged selector, used as subselector for MultiSelector/CompositeSelector/DirectionalSelector Conserves memory by pointing to a internal ID range, end is inclusive

Fields

begin: AnnotationHandle

end: AnnotationHandle

with_text: bool

Implementations

impl Selector

pub fn kind(&self) -> SelectorKind

Returns a SelectorKind identifying the type of selector

pub fn is_complex(&self) -> bool

A complex selector targets multiple targets. Note the internal ranged selector is not counted as part of this category.

pub fn to_json(&self, store: &AnnotationStore) -> Result<String, StamError>

Writes a Selector to a STAM JSON string, with appropriate formatting

pub fn to_json_compact( &self, store: &AnnotationStore ) -> Result<String, StamError>

Writes a Selector to a STAM JSON string, without indentation

pub fn subselectors(&self) -> Option<&[Selector]>

Returns all subselectors. Use [self.iter()] instead if you want an iterator with more functionality.

pub fn textselection<'store>( &self, store: &'store AnnotationStore ) -> Option<&'store TextSelection>

Returns the textselection this selector points at, if any

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

Returns the textselection handle this selector points at, if any

pub fn resource_handle(&self) -> Option<TextResourceHandle>

Returns the handle of the resource this selector points at, if any

pub fn offset(&self, store: &AnnotationStore) -> Option<Offset>

Returns the associated offset if the selector carries one

pub fn offset_with_mode( &self, store: &AnnotationStore, override_mode: Option<OffsetMode> ) -> Option<Offset>

Returns the associated offset if the selector carries one You may set override_mode if you want to override the OffsetMode rather than take it from the selector

impl Selector

pub fn iter<'a>( &'a self, store: &'a AnnotationStore, recurse_annotation: bool ) -> SelectorIter<'a>

Returns an iterator that yields all Selectors under a particular selector, including the selcetor in question as well. The parameter recurse_annotation determines whether an AnnotationSelector will be resolved recursively or not (finding all it points at)

Trait Implementations

impl Clone for Selector

fn clone(&self) -> Selector

Returns a copy of the value.

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

Performs copy-assignment from source.

impl DataSize for Selector

const IS_DYNAMIC: bool = true

If true, the type has a heap size that can vary at runtime, depending on the actual value.

const STATIC_HEAP_SIZE: usize = 8usize

The amount of space a value of the type always occupies. If IS_DYNAMIC is false, this is the total amount of heap memory occupied by the value. Otherwise this is a lower bound.

fn estimate_heap_size(&self) -> usize

Estimates the size of heap memory taken up by this value.

impl Debug for Selector

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

Formats the value using the given formatter.

impl<'bytes, Ctx> Decode<'bytes, Ctx> for Selector

fn decode( __d777: &mut Decoder<'bytes>, __ctx777: &mut Ctx ) -> Result<Selector, Error>

Decode a value using the given Decoder.

fn nil() -> Option<Self>

If possible, return a nil value of Self.

impl<Ctx> Encode<Ctx> for Selector

fn encode<__W777>( &self, __e777: &mut Encoder<__W777>, __ctx777: &mut Ctx ) -> Result<(), Error<__W777::Error>>

where __W777: Write,

Encode a value of this type using the given Encoder.

fn is_nil(&self) -> bool

Is this value of Self a nil value?

impl From<&Selector> for SelectorKind

fn from(selector: &Selector) -> Self

Converts to this type from the input type.

impl PartialEq for Selector

fn eq(&self, other: &Selector) -> 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 StructuralPartialEq for Selector