Struct stam::AnnotationStore

pub struct AnnotationStore { /* private fields */ }

An Annotation Store is an unordered collection of annotations, resources and annotation data sets. It can be seen as the root of the graph model and the glue that holds everything together. It is the entry point for any stam model.

Implementations

impl AnnotationStore

pub fn with_annotation( self, builder: AnnotationBuilder<'_> ) -> Result<Self, StamError>

Builds and adds an annotation

pub fn with_annotations( self, builders: Vec<AnnotationBuilder<'_>> ) -> Result<Self, StamError>

Builds and adds multiple annotations

pub fn insert_data( &mut self, dataitem: AnnotationDataBuilder<'_> ) -> Result<(AnnotationDataSetHandle, AnnotationDataHandle), StamError>

Builds and inserts an AnnotationData item

pub fn annotate( &mut self, builder: AnnotationBuilder<'_> ) -> Result<AnnotationHandle, StamError>

Builds and inserts an annotation In a builder pattenr, use [Self.with_annotation()] instead

pub fn annotate_builders( &mut self, builders: Vec<AnnotationBuilder<'_>> ) -> Result<(), StamError>

Builds and inserts using multiple annotation builders

impl AnnotationStore

pub fn new() -> Self

Creates a new empty annotation store with a default configuraton, add the [AnnotationStore.with_config()] to provide a custom one

pub fn from_file(filename: &str, config: Config) -> Result<Self, StamError>

Loads an AnnotationStore from a file (STAM JSON or another supported format) The file must contain a single object which has “@type”: “AnnotationStore”

pub fn from_str(string: &str, config: Config) -> Result<Self, StamError>

Loads an AnnotationStore from a STAM JSON string The string must contain a single object which has “@type”: “AnnotationStore”

pub fn with_file(self, filename: &str) -> Result<Self, StamError>

Merge another annotation store STAM JSON file into this one

pub fn annotations_filename(&self) -> Option<&Path>

Returns the filename associated with this annotation store for storage of annotations Only used for STAM CSV, not for STAM JSON.

pub fn annotate_from_file( &mut self, filename: &str ) -> Result<&mut Self, StamError>

Load a JSON file containing an array of annotations in STAM JSON

pub fn to_file(&mut self, filename: &str) -> Result<(), StamError>

Write the annotation store and all files below it to file (STAM JSON or other supported formats likes STAM CSV) The filetype is determined by the extension.

pub fn merge_from_builder( &mut self, builder: AnnotationStoreBuilder<'_> ) -> Result<&mut Self, StamError>

Merge another annotation store, represented by a builder, into this one It’s a fairly low-level function which you often don’t need directly, use AnnotationStore.with_file() instead.

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

Shortcut to write an AnnotationStore to a STAM JSON file, writes to the same file as was loaded. Returns an error if no filename was associated yet. Use [AnnotationStore.to_file] instead if you want to write elsewhere.

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

Returns the ID of the annotation store (if any)

pub fn with_id(self, id: String) -> Self

Sets the ID of the annotation store in a builder pattern

pub fn add_resource_from_file( &mut self, filename: &str ) -> Result<TextResourceHandle, StamError>

Shortcut method that calls add_resource under the hood and returns a reference to it

pub fn resolve_annotation_id( &self, id: &str ) -> Result<AnnotationHandle, StamError>

Get an annotation handle from an ID. Shortcut wraps arround get_handle()

pub fn resolve_dataset_id( &self, id: &str ) -> Result<AnnotationDataSetHandle, StamError>

Get an annotation dataset handle from an ID. Shortcut wraps arround get_handle()

pub fn resolve_resource_id( &self, id: &str ) -> Result<TextResourceHandle, StamError>

Get an annotation dataset handle from an ID. Shortcut wraps arround get_handle()

pub fn annotations<'a>(&'a self) -> StoreIter<'a, Annotation>

Returns an iterator over all annotations (Annotation) in the store

pub fn resources<'a>(&'a self) -> StoreIter<'a, TextResource>

Returns an iterator over all text resources (TextResource instances) in the store

pub fn annotationsets<'a>(&'a self) -> StoreIter<'a, AnnotationDataSet>

Returns an iterator over all AnnotationDataSet instances in the store

pub fn annotations_len(&self) -> usize

Returns the number of annotations in the store (deletions are not substracted)

pub fn resources_len(&self) -> usize

Returns the number of resources in the store (deletions are not substracted)

pub fn annotationsets_len(&self) -> usize

Returns the number of datasets in the store (deletions are not substracted)

pub fn annotations_by_resource( &self, resource_handle: TextResourceHandle ) -> Option<impl Iterator<Item = AnnotationHandle> + '_>

Returns all annotations that reference any text selection in the resource. This is a low-level method, use [WrappedItem<TextResource>.annotations()] instead for higher-level access.

Use [Self.annotations_by_resource_metadata()] instead if you are looking for annotations that reference the resource as is

pub fn annotations_by_resource_metadata( &self, resource_handle: TextResourceHandle ) -> Option<&Vec<AnnotationHandle>>

This only returns annotations that directly point at the resource, i.e. are metadata for it. It does not include annotations that This is a low-level method, use [WrappedItem<TextResource>.annotations(_metadata] instead for higher-level access.

point at a text in the resource, use [Self.annotations_by_resource()] instead for those.

pub fn annotations_by_textselection( &self, resource_handle: TextResourceHandle, textselection: &TextSelection ) -> Option<&Vec<AnnotationHandle>>

Find all annotations with a particular textselection. This is a quick lookup in the reverse index and returns a reference to a vector. This is a low-level method, use [WrappedItem<TextSelection>.annotations()] instead for higher-level access.

pub fn annotations_by_offset<'a>( &'a self, resource_handle: TextResourceHandle, offset: &Offset ) -> Option<&'a Vec<AnnotationHandle>>

Find all annotations with a particular offset (exact). This is a lookup in the reverse index and returns a reference to a vector. This is a low-level method.

pub fn annotations_by_annotation_reverse( &self, annotation_handle: AnnotationHandle ) -> Option<&Vec<AnnotationHandle>>

Find all annotations that overlap with a particular offset. Find all annotations referenced by the specified annotation (i.e. annotations that point AT the specified annotation). This is a lookup in the reverse index and returns a reference to a vector

This is a low-lever function, use [WrappedItem<Annotation>.annotations_reverse()] instead. Use [wrappeditem<annotation>.annotations()] if you are looking for the annotations that an annotation points at.

pub fn annotations_by_annotationset( &self, annotationset_handle: AnnotationDataSetHandle ) -> Option<impl Iterator<Item = AnnotationHandle> + '_>

Returns all annotations that reference any keys/data in an annotationset Use [Self.annotations_by_annotationset_metadata()] instead if you are looking for annotations that reference the dataset as is This is a low-level method. Use [WrappedItem<AnnotationDataSet>.annotations()] instead.

pub fn annotations_by_annotationset_metadata( &self, annotationset_handle: AnnotationDataSetHandle ) -> Option<&Vec<AnnotationHandle>>

Find all annotations referenced by the specified annotationset. This is a lookup in the reverse index and returns a reference to a vector. This only returns annotations that directly point at the dataset, i.e. are metadata for it. This is a low-level method. Use [WrappedItem<AnnotationDataSet>.annotations_metadata()] instead.

pub fn annotations_by_data( &self, annotationset_handle: AnnotationDataSetHandle, data_handle: AnnotationDataHandle ) -> Option<&Vec<AnnotationHandle>>

Find all annotations referenced by data. This is a lookup in the reverse index and return a reference. This is a low-level method. Use [WrappedItem<AnnotationData>.annotations()] instead.

pub fn annotations_by_key( &self, annotationset_handle: AnnotationDataSetHandle, datakey_handle: DataKeyHandle ) -> Option<impl Iterator<Item = AnnotationHandle> + '_>

Find all annotations referenced by key This is a low-level method

pub fn textselection<'b>( &self, selector: &Selector, subselectors: Option<impl Iterator<Item = &'b Selector>> ) -> Result<WrappedItem<'_, TextSelection>, StamError>

Retrieve a TextSelection given a specific TextSelector. Does not work with other more complex selectors, use for instance [AnnotationStore::textselections_by_annotation] instead for those.

If multiple AnnotationSelectors are involved, they can be passed as subselectors and will further refine the TextSelection, but this is usually not invoked directly but via [AnnotationStore::textselections_by_annotation]

pub fn selector( &mut self, item: SelectorBuilder<'_> ) -> Result<Selector, StamError>

Builds a Selector based on its SelectorBuilder, this will produce an error if the selected resource does not exist.

pub fn annotation( &self, annotation: &Item<'_, Annotation> ) -> Option<WrappedItem<'_, Annotation>>

Method to retrieve an annotation from the store.

Returns a reference to Annotation that is wrapped in a fat pointer (WrappedItem<Annotation>) that also contains reference to the store and which is immediately implements various methods for working with the type. If you need a more performant low-level method, use StoreFor<T>::get() instead.

pub fn annotationset( &self, annotationset: &Item<'_, AnnotationDataSet> ) -> Option<WrappedItem<'_, AnnotationDataSet>>

Get an [AnnotationDataSet'] by reference (as a fat pointer [WrappedItem<AnnotationDataSet’]) Returns None if it does not exist.

pub fn resource( &self, resource: &Item<'_, TextResource> ) -> Option<WrappedItem<'_, TextResource>>

Get a [TextResource'] by reference (as a fat pointer [WrappedItem<TextResource’]) Returns None if it does not exist.

pub fn index_totalcount(&self) -> (usize, usize, usize, usize, usize)

Returns total counts for each of the reverse indices

• dataset_data_annotation_map
• textrelationmap
• resource_annotation_map
• dataset_annotation_map
• annotation_annotation_map

impl AnnotationStore

pub fn find_text_regex<'store, 'r>( &'store self, expressions: &'r [Regex], precompiledset: &'r Option<RegexSet>, allow_overlap: bool ) -> impl Iterator<Item = FindRegexMatch<'store, 'r>>

Searches for text in all resources using one or more regular expressions, returns an iterator over TextSelections along with the matching expression, this See [TextResource.find_text_regex()]. Note that this method, unlike its counterpart [TextResource.find_text_regex()], silently ignores any deeper errors that might occur.

impl AnnotationStore

pub fn to_csv_files(&self, filename: &str) -> Result<(), StamError>

Saves all files as CSV. It is better to use AnnotationStore::save() instead, setting [AnnotationStore::set_dataformat(DataFormat::Csv)] before invocation.

Trait Implementations

impl AssociatedFile for AnnotationStore

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

Returns the filename associated with this annotation store

fn with_filename(self, filename: &str) -> Self

fn set_filename(&mut self, filename: &str) -> &mut Self

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

Returns the filename without (known!) extension. The extension must be a known extension used by STAM for this to work.

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

Serializes the filename ready for use with STAM JSON’s @include or STAM CSV. It basically only strips the workdir component, if any.

impl Configurable for AnnotationStore

fn config(&self) -> &Config

Return the associated configuration

fn set_config(&mut self, config: Config) -> &mut Self

Sets the configuration, this will also overwrite all underlying configurations for annotation data sets and resources!

fn config_mut(&mut self) -> &mut Config

fn with_config(self, config: Config) -> Self

Builder pattern to associate a configuration

impl Debug for AnnotationStore

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

Formats the value using the given formatter.

impl Default for AnnotationStore

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AnnotationStore

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AnnotationStore

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

Serialize this value into the given Serde serializer.

impl StoreFor<Annotation> for AnnotationStore

fn preremove(&mut self, handle: AnnotationHandle) -> Result<(), StamError>

called before the item is removed from the store updates the relation maps, no need to call manually

fn store(&self) -> &Store<Annotation>

Get a reference to the entire store for the associated type

fn store_mut(&mut self) -> &mut Store<Annotation>

Get a mutable reference to the entire store for the associated type

fn idmap(&self) -> Option<&IdMap<AnnotationHandle>>

Get a reference to the id map for the associated type, mapping global ids to internal ids

fn idmap_mut(&mut self) -> Option<&mut IdMap<AnnotationHandle>>

Get a mutable reference to the id map for the associated type, mapping global ids to internal ids

fn store_typeinfo() -> &'static str

fn inserted(&mut self, handle: AnnotationHandle) -> Result<(), StamError>

Called after an item was inserted to the store Allows the store to do further bookkeeping like updating relation maps

fn insert(&mut self, item: T) -> Result<T::HandleType, StamError>

Adds an item to the store. Returns a handle to it upon success.

fn preinsert(&self, item: &mut T) -> Result<(), StamError>

Called prior to inserting an item into to the store If it returns an error, the insert will be cancelled. Allows for bookkeeping such as inheriting configuration parameters from parent to the item

fn add(self, item: T) -> Result<Self, StamError>where Self: Sized,

fn has<'a, 'b>(&'a self, item: &Item<'b, T>) -> bool

Returns true if the store has the item

unsafe fn get_unchecked(&self, handle: T::HandleType) -> Option<&T>

Get a reference to an item from the store, by handle, without checking validity.

fn get<'a, 'b>(&'a self, item: &Item<'b, T>) -> Result<&'a T, StamError>

Get a reference to an item from the store

fn get_mut<'a, 'b>(&mut self, item: &Item<'b, T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID

fn remove(&mut self, handle: T::HandleType) -> Result<(), StamError>

Removes an item by handle, returns an error if the item has dependencies and can’t be removed

fn resolve_id(&self, id: &str) -> Result<T::HandleType, StamError>

Resolves an ID to a handle You usually don’t want to call this directly

fn owns(&self, item: &T) -> Option<bool>

Tests if the item is owner by the store, returns None if ownership is unknown

fn iter<'a>(&'a self) -> StoreIter<'a, T> where T: Storable<StoreType = Self>,

Iterate over the store

fn iter_mut<'a>(&'a mut self) -> StoreIterMut<'a, T>

Iterate over the store, mutably

fn next_handle(&self) -> T::HandleType

Return the internal id that will be assigned for the next item to the store

fn last_handle(&self) -> T::HandleType

Return the internal id that was assigned to last inserted item

fn bind(&mut self, item: T) -> Result<T, StamError>

This binds an item to the store PRIOR to it being actually added You should never need to call this directly (it can only be called once per item anyway).

fn wrap<'a>(&'a self, item: &'a T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store This method performs some extra checks to verify if the item is indeed owned by the store and returns an error if not.

fn wrap_owned<'a>(&'a self, item: T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store Ownership is retained with this method, i.e. the store does NOT own the item.

fn wrap_store<'a>(&'a self) -> WrappedStore<'_, T, Self>where Self: Sized,

Wraps the entire store along with a reference to self Low-level method that you won’t need

impl StoreFor<AnnotationDataSet> for AnnotationStore

fn preinsert(&self, item: &mut AnnotationDataSet) -> Result<(), StamError>

Called prior to inserting an item into to the store If it returns an error, the insert will be cancelled. Allows for bookkeeping such as inheriting configuration parameters from parent to the item

fn preremove( &mut self, handle: AnnotationDataSetHandle ) -> Result<(), StamError>

called before the item is removed from the store updates the relation maps, no need to call manually

fn store(&self) -> &Store<AnnotationDataSet>

Get a reference to the entire store for the associated type

fn store_mut(&mut self) -> &mut Store<AnnotationDataSet>

Get a mutable reference to the entire store for the associated type

fn idmap(&self) -> Option<&IdMap<AnnotationDataSetHandle>>

Get a reference to the id map for the associated type, mapping global ids to internal ids

fn idmap_mut(&mut self) -> Option<&mut IdMap<AnnotationDataSetHandle>>

Get a mutable reference to the id map for the associated type, mapping global ids to internal ids

fn store_typeinfo() -> &'static str

fn insert(&mut self, item: T) -> Result<T::HandleType, StamError>

Adds an item to the store. Returns a handle to it upon success.

fn inserted(&mut self, handle: T::HandleType) -> Result<(), StamError>

Called after an item was inserted to the store Allows the store to do further bookkeeping like updating relation maps

fn add(self, item: T) -> Result<Self, StamError>where Self: Sized,

fn has<'a, 'b>(&'a self, item: &Item<'b, T>) -> bool

Returns true if the store has the item

unsafe fn get_unchecked(&self, handle: T::HandleType) -> Option<&T>

Get a reference to an item from the store, by handle, without checking validity.

fn get<'a, 'b>(&'a self, item: &Item<'b, T>) -> Result<&'a T, StamError>

Get a reference to an item from the store

fn get_mut<'a, 'b>(&mut self, item: &Item<'b, T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID

fn remove(&mut self, handle: T::HandleType) -> Result<(), StamError>

Removes an item by handle, returns an error if the item has dependencies and can’t be removed

fn resolve_id(&self, id: &str) -> Result<T::HandleType, StamError>

Resolves an ID to a handle You usually don’t want to call this directly

fn owns(&self, item: &T) -> Option<bool>

Tests if the item is owner by the store, returns None if ownership is unknown

fn iter<'a>(&'a self) -> StoreIter<'a, T> where T: Storable<StoreType = Self>,

Iterate over the store

fn iter_mut<'a>(&'a mut self) -> StoreIterMut<'a, T>

Iterate over the store, mutably

fn next_handle(&self) -> T::HandleType

Return the internal id that will be assigned for the next item to the store

fn last_handle(&self) -> T::HandleType

Return the internal id that was assigned to last inserted item

fn bind(&mut self, item: T) -> Result<T, StamError>

This binds an item to the store PRIOR to it being actually added You should never need to call this directly (it can only be called once per item anyway).

fn wrap<'a>(&'a self, item: &'a T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store This method performs some extra checks to verify if the item is indeed owned by the store and returns an error if not.

fn wrap_owned<'a>(&'a self, item: T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store Ownership is retained with this method, i.e. the store does NOT own the item.

fn wrap_store<'a>(&'a self) -> WrappedStore<'_, T, Self>where Self: Sized,

Wraps the entire store along with a reference to self Low-level method that you won’t need

impl StoreFor<TextResource> for AnnotationStore

fn store(&self) -> &Store<TextResource>

Get a reference to the entire store for the associated type

fn store_mut(&mut self) -> &mut Store<TextResource>

Get a mutable reference to the entire store for the associated type

fn idmap(&self) -> Option<&IdMap<TextResourceHandle>>

Get a reference to the id map for the associated type, mapping global ids to internal ids

fn idmap_mut(&mut self) -> Option<&mut IdMap<TextResourceHandle>>

Get a mutable reference to the id map for the associated type, mapping global ids to internal ids

fn preinsert(&self, item: &mut TextResource) -> Result<(), StamError>

Called prior to inserting an item into to the store If it returns an error, the insert will be cancelled. Allows for bookkeeping such as inheriting configuration parameters from parent to the item

fn preremove(&mut self, handle: TextResourceHandle) -> Result<(), StamError>

called before the item is removed from the store updates the relation maps, no need to call manually

fn store_typeinfo() -> &'static str

fn insert(&mut self, item: T) -> Result<T::HandleType, StamError>

Adds an item to the store. Returns a handle to it upon success.

fn inserted(&mut self, handle: T::HandleType) -> Result<(), StamError>

Called after an item was inserted to the store Allows the store to do further bookkeeping like updating relation maps

fn add(self, item: T) -> Result<Self, StamError>where Self: Sized,

fn has<'a, 'b>(&'a self, item: &Item<'b, T>) -> bool

Returns true if the store has the item

unsafe fn get_unchecked(&self, handle: T::HandleType) -> Option<&T>

Get a reference to an item from the store, by handle, without checking validity.

fn get<'a, 'b>(&'a self, item: &Item<'b, T>) -> Result<&'a T, StamError>

Get a reference to an item from the store

fn get_mut<'a, 'b>(&mut self, item: &Item<'b, T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID

fn remove(&mut self, handle: T::HandleType) -> Result<(), StamError>

Removes an item by handle, returns an error if the item has dependencies and can’t be removed

fn resolve_id(&self, id: &str) -> Result<T::HandleType, StamError>

Resolves an ID to a handle You usually don’t want to call this directly

fn owns(&self, item: &T) -> Option<bool>

Tests if the item is owner by the store, returns None if ownership is unknown

fn iter<'a>(&'a self) -> StoreIter<'a, T> where T: Storable<StoreType = Self>,

Iterate over the store

fn iter_mut<'a>(&'a mut self) -> StoreIterMut<'a, T>

Iterate over the store, mutably

fn next_handle(&self) -> T::HandleType

Return the internal id that will be assigned for the next item to the store

fn last_handle(&self) -> T::HandleType

Return the internal id that was assigned to last inserted item

fn bind(&mut self, item: T) -> Result<T, StamError>

This binds an item to the store PRIOR to it being actually added You should never need to call this directly (it can only be called once per item anyway).

fn wrap<'a>(&'a self, item: &'a T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store This method performs some extra checks to verify if the item is indeed owned by the store and returns an error if not.

fn wrap_owned<'a>(&'a self, item: T) -> Result<WrappedItem<'_, T>, StamError>where T: Storable<StoreType = Self>,

Wraps the item in a smart pointer that also holds a reference to this store Ownership is retained with this method, i.e. the store does NOT own the item.

fn wrap_store<'a>(&'a self) -> WrappedStore<'_, T, Self>where Self: Sized,

Wraps the entire store along with a reference to self Low-level method that you won’t need

impl ToCsv for AnnotationStorewhere Self: TypeInfo + Configurable,

fn to_csv_writer<W>(&self, writer: W, table: CsvTable) -> Result<(), StamError>where W: Write,

Writes CSV output, for the specified table, to the writer

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

Writes this structure to a file The actual dataformat can be set via config, the default is STAM JSON. Note: This only writes a single table! Just use [AnnotationStore.save()] to write everything.

fn to_csv_string(&self, table: Option<CsvTable>) -> Result<String, StamError>

impl ToJson for AnnotationStore

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

impl<'a> TryFrom<AnnotationStoreBuilder<'a>> for AnnotationStore

type Error = StamError

The type returned in the event of a conversion error.

fn try_from(builder: AnnotationStoreBuilder<'_>) -> Result<Self, StamError>

Performs the conversion.

impl TypeInfo for AnnotationStore

fn typeinfo() -> Type