Struct stam::AnnotationDataSet

pub struct AnnotationDataSet { /* private fields */ }

An AnnotationDataSet stores the keys DataKey and values AnnotationData (which in turn encapsulates DataValue) that are used by annotations. It effectively defines a certain vocabulary, i.e. key/value pairs. The AnnotationDataSet does not store the Annotation instances, those are in the AnnotationStore. The datasets themselves are also held by the AnnotationStore.

See the top-level documentation for AnnotationStore for a complete usage example on instantiating a data set.

Implementations

impl AnnotationDataSet

pub fn new(config: Config) -> Self

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

Loads an AnnotationDataSet from file (STAM JSON or other supported format). For STAM JSON, the file must contain a single object which has “@type”: “AnnotationDataSet”

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

Merge another AnnotationDataSet from file (STAM JSON or other supported format). Note: The ID and filename of the set will not be overwritten if already set, reserialising the store will produce a single new set.

pub fn with_data<'a>( self, key: impl Into<BuildItem<'a, DataKey>>, value: impl Into<DataValue> + Debug ) -> Result<Self, StamError>

Adds new AnnotationData to the dataset, this should be

pub fn with_data_with_id<'a>( self, key: impl Into<BuildItem<'a, DataKey>>, value: impl Into<DataValue> + Debug, id: impl Into<BuildItem<'a, AnnotationData>> ) -> Result<Self, StamError>

Adds new AnnotationData to the dataset, this should be

pub fn data_by_value( &self, key: impl Request<DataKey>, value: &DataValue ) -> Option<&AnnotationData>

Finds the AnnotationData in the annotation dataset. Returns one match. This is a low level method, use the similar [crate::ResultItem<AnnotationDataSet>.data_by_value()] for a higher level version.

pub fn insert_data<'a>( &mut self, id: impl Into<BuildItem<'a, AnnotationData>>, key: impl Into<BuildItem<'a, DataKey>>, value: impl Into<DataValue> + Debug, safety: bool ) -> Result<AnnotationDataHandle, StamError>

Adds new AnnotationData to the dataset. Use Self::with_data() instead if you are using a regular builder pattern. If the data already exists, this returns a handle to the existing data and inserts nothing new. If the data is new, it returns a handle to the new data.

The safety parameter should be set to true in normal circumstances, it will check if the data already exists if it has no ID, and reuse that. If set to false, data will be inserted as a duplicate.

Note: if you don’t want to set an ID (first argument), you can just pass AnyId::None or “”.into()

pub fn build_insert_data( &mut self, dataitem: AnnotationDataBuilder<'_>, safety: bool ) -> Result<AnnotationDataHandle, StamError>

Build and insert data into the dataset, similar to Self::insert_data() and Self::with_data(), but takes a prepared AnnotationDataBuilder instead.

pub fn data(&self) -> StoreIter<'_, AnnotationData>

Returns an iterator over all the data (AnnotationData) in this set, the iterator returns references to AnnotationData.

pub fn keys(&self) -> StoreIter<'_, DataKey>

Returns an iterator over all the keys (DataKey) in this set, the iterator in returns references to DataKey

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

Retrieve a key in this set

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

Retrieve a AnnotationData in this set

pub fn data_by_key( &self, key: impl Request<DataKey> ) -> Option<&Vec<AnnotationDataHandle>>

Returns data by key, does a lookup in the reverse index and returns a reference to it. This is a low-level method. use [ResultItem<DataKey>.data()] instead.

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

Sets the ID of the dataset in a builder pattern

pub fn keys_len(&self) -> usize

Writes a //Returns the number of keys in the store (deletions are not substracted)

pub fn data_len(&self) -> usize

pub fn meminfo(&self) -> usize

pub fn shrink_to_fit(&mut self)

pub fn strip_data_ids(&mut self)

Strip public identifiers from annotation data This will not affect any internal references but will render any references from external sources impossible.

Trait Implementations

impl AssociatedFile for AnnotationDataSet

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

Get the filename for stand-off file specified using @include (if any)

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

Get the filename for stand-off file specified using @include (if any)

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

where Self: Sized,

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 Clone for AnnotationDataSet

fn clone(&self) -> AnnotationDataSet

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Configurable for AnnotationDataSet

fn config(&self) -> &Config

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

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

Setter to associate a configuration

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

Builder pattern to associate a configuration

impl DataSize for AnnotationDataSet

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 = 0usize

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 AnnotationDataSet

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

Formats the value using the given formatter.

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

fn decode( __d777: &mut Decoder<'bytes>, __ctx777: &mut Ctx ) -> Result<AnnotationDataSet, 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 AnnotationDataSet

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 FromCsv for AnnotationDataSet

fn from_csv_reader( reader: Box<dyn BufRead>, filename: Option<&str>, config: Config ) -> Result<Self, StamError>

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

impl FromJson for AnnotationDataSet

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

Loads an AnnotationDataSet from a STAM JSON file, as a builder The file must contain a single object which has “@type”: “AnnotationDataSet” If include is true, the file will be included via the @include mechanism, and is kept external upon serialization If workdir is set, the file will be searched for in the workdir if needed

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

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

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

Merges an AnnotationDataSet from a STAM JSON file into the current one The file must contain a single object which has “@type”: “AnnotationDataSet”

fn merge_json_str(&mut self, string: &str) -> Result<(), StamError>

Merges an AnnotationDataSet from a STAM JSON string into the current one The string must contain a single object which has “@type”: “AnnotationDataSet”

impl PartialEq for AnnotationDataSet

fn eq(&self, other: &AnnotationDataSet) -> 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> Request<AnnotationDataSet> for AnnotationDataSetHandle

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

where S: StoreFor<AnnotationDataSet>,

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> Request<AnnotationDataSet> for Option<AnnotationDataSetHandle>

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

where S: StoreFor<AnnotationDataSet>,

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

fn any(&self) -> bool

Represents a request for any value in certain contexts

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

impl SelfSelector for AnnotationDataSet

fn to_selector(&self) -> Result<Selector, StamError>

Returns a selector to this resource

impl Serialize for AnnotationDataSet

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Storable for AnnotationDataSet

type HandleType = AnnotationDataSetHandle

type StoreHandleType = ()

type FullHandleType = <AnnotationDataSet as Storable>::HandleType

type StoreType = AnnotationStore

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

Get the public identifier

fn with_id(self, id: impl Into<String>) -> Self

Builder pattern to set the public ID

fn handle(&self) -> Option<Self::HandleType>

Retrieve the internal (numeric) id. For any type T in StoreFor<T>, this may return None only in the initial stage when it is still unbounded to a store, so this is almost always safe to unwrap when used in the public API.

fn with_handle(self, handle: AnnotationDataSetHandle) -> Self

Set the internal ID for an item. May only be called once just after instantiation. This is a low-level API method that can not be used publicly due to ownership restrictions.

fn carries_id() -> bool

Does this type support an ID?

fn fullhandle( _storehandle: Self::StoreHandleType, handle: Self::HandleType ) -> Self::FullHandleType

fn handle_or_err(&self) -> Result<Self::HandleType, StamError>

Like Self::handle() but returns a StamError::Unbound error if there is no internal id.

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

Generate a temporary public ID based on the internal handle.

fn as_resultitem<'store>( &'store self, store: &'store Self::StoreType, rootstore: &'store AnnotationStore ) -> ResultItem<'store, Self>

where Self: Sized,

Returns the item of type T as a ResultItem<T>, i.e. a wrapped reference that includes a reference to both this item as well as the store that owns it. All high-level API functions are implemented on such Result types. You should not need to invoke this yourself.

fn generate_id(self, idmap: Option<&mut IdMap<Self::HandleType>>) -> Self

where Self: Sized,

Generate a random ID in a given idmap (adds it to the map and assigns it to the item) This is a low-level API method that can not be used publicly due to ownership restrictions.

impl StoreFor<AnnotationData> for AnnotationDataSet

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

Get a reference to the entire store for the associated type This is a low-level API method.

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

Get a mutable reference to the entire store for the associated type This is a low-level API method.

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

Get a reference to the id map for the associated type, mapping global ids to internal ids This is a low-level API method.

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

Get a mutable reference to the id map for the associated type, mapping global ids to internal ids This is a low-level API method.

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 add(self, item: T) -> Result<Self, StamError>

where Self: Sized,

Inserts items into the store using a builder pattern

fn has(&self, item: impl Request<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(&self, item: impl Request<T>) -> Result<&T, StamError>

Get a reference to an item from the store This is a low-level API method, you usually want to use dedicated high-level methods like AnnotationStore::annotation() instead.

fn get_mut(&mut self, item: impl Request<T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID This is a low-level API method

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. Also works for temporary IDs if enabled. This is a low-level API method. You usually don’t want to call this directly.

fn iter(&self) -> StoreIter<'_, T>

where T: Storable<StoreType = Self>,

Iterate over all items in the store This is a low-level API method, use dedicated high-level iterators like annotations(), resources() instead.

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

Iterate over the store, mutably This is a low-level API method.

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

Return the internal id that will be assigned for the next item to the store This is a low-level API method.

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

Return the internal id that was assigned to last inserted item This is a low-level API method.

impl StoreFor<AnnotationDataSet> for AnnotationStore

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

Get a reference to the entire store for the associated type This is a low-level API method.

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

Get a mutable reference to the entire store for the associated type This is a low-level API method.

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

Get a reference to the id map for the associated type, mapping global ids to internal ids This is a low-level API method.

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 This is a low-level API method.

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 add(self, item: T) -> Result<Self, StamError>

where Self: Sized,

Inserts items into the store using a builder pattern

fn has(&self, item: impl Request<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(&self, item: impl Request<T>) -> Result<&T, StamError>

Get a reference to an item from the store This is a low-level API method, you usually want to use dedicated high-level methods like AnnotationStore::annotation() instead.

fn get_mut(&mut self, item: impl Request<T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID This is a low-level API method

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. Also works for temporary IDs if enabled. This is a low-level API method. You usually don’t want to call this directly.

fn iter(&self) -> StoreIter<'_, T>

where T: Storable<StoreType = Self>,

Iterate over all items in the store This is a low-level API method, use dedicated high-level iterators like annotations(), resources() instead.

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

Iterate over the store, mutably This is a low-level API method.

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

Return the internal id that will be assigned for the next item to the store This is a low-level API method.

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

Return the internal id that was assigned to last inserted item This is a low-level API method.

impl StoreFor<DataKey> for AnnotationDataSet

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

Get a reference to the entire store for the associated type This is a low-level API method.

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

Get a mutable reference to the entire store for the associated type This is a low-level API method.

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

Get a reference to the id map for the associated type, mapping global ids to internal ids This is a low-level API method.

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

Get a mutable reference to the id map for the associated type, mapping global ids to internal ids This is a low-level API method.

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 add(self, item: T) -> Result<Self, StamError>

where Self: Sized,

Inserts items into the store using a builder pattern

fn has(&self, item: impl Request<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(&self, item: impl Request<T>) -> Result<&T, StamError>

Get a reference to an item from the store This is a low-level API method, you usually want to use dedicated high-level methods like AnnotationStore::annotation() instead.

fn get_mut(&mut self, item: impl Request<T>) -> Result<&mut T, StamError>

Get a mutable reference to an item from the store by internal ID This is a low-level API method

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. Also works for temporary IDs if enabled. This is a low-level API method. You usually don’t want to call this directly.

fn iter(&self) -> StoreIter<'_, T>

where T: Storable<StoreType = Self>,

Iterate over all items in the store This is a low-level API method, use dedicated high-level iterators like annotations(), resources() instead.

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

Iterate over the store, mutably This is a low-level API method.

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

Return the internal id that will be assigned for the next item to the store This is a low-level API method.

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

Return the internal id that was assigned to last inserted item This is a low-level API method.

impl ToCsv for AnnotationDataSet

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 AnnotationDataSet

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 TypeInfo for AnnotationDataSet

fn typeinfo() -> Type

Return the type (introspection).

fn temp_id_prefix() -> &'static str

Return the prefix for temporary identifiers of this type