Struct stam::TextResource

pub struct TextResource { /* private fields */ }

This holds the textual resource to be annotated. It holds the full text in memory.

The text SHOULD be in Unicode Normalization Form C (NFC) but MAY be in another unicode normalization forms.

Implementations

impl TextResource

pub fn new(id: String, config: Config) -> Self

Instantiates a new completely empty TextResource

pub fn builder() -> TextResourceBuilder

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

Create a new TextResource from file, the text will be loaded into memory entirely

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

Loads a text for the TextResource from file (STAM JSON or plain text), the text will be loaded into memory entirely The use of [Self.from_file()] is preferred instead. This method can be dangerous if it modifies any existing text of a resource.

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

Sets the filename for writing, will force a write to it when the underlying store is serialized. CAUTION: This method does not load a file so it will overwrite any existing file!

pub fn with_string(self, text: String) -> Self

Sets the text of the TextResource from string, kept in memory entirely The use of [Self.from_string()] is preferred instead. This method can be dangerous if it modifies any existing text of a resource.

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

Writes a plain text file

pub fn from_string(id: String, text: String, config: Config) -> Self

Create a new TextResource from string, kept in memory entirely

pub fn known_textselection( &self, offset: &Offset ) -> Result<Option<TextSelectionHandle>, StamError>

Finds a known text selection, as specified by the offset. Known textselections are associated with an annotation. Returns a handle. Use the higher-level method [Self.textselection()] instead if you want to return a textselection regardless of whether it’s known or not.

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

Returns an unsorted iterator over all textselections in this resource Use this only if order doesn’t matter for. For a sorted version, use Self::iter() or Self::range() instead.

pub fn textselections_len(&self) -> usize

pub fn range<'a>(&'a self, begin: usize, end: usize) -> TextSelectionIter<'a>

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 iter<'a>(&'a self) -> TextSelectionIter<'a>

Returns a sorted double-ended iterator over all textselections in this resource For unsorted (slightly more performant), use TextResource::textselections() instead.

pub fn positions<'a>( &'a self, mode: PositionMode ) -> Box<dyn Iterator<Item = &'a usize> + 'a>

Returns a sorted iterator over all absolute positions (begin aligned cursors) that are in use By passing a PositionMode parameter you can specify whether you want only positions where a textselection begins, ends or both.

pub fn position(&self, index: usize) -> Option<&PositionIndexItem>

Lookup a position (unicode point) in the PositionIndex. Low-level function. Only works for positions at which a TextSelection starts or ends (non-inclusive), returns None otherwise

pub fn positionindex_len(&self) -> usize

Returns the number of positions in the positionindex

impl TextResource

pub fn textselections_by_operator_ref<'store, 'q>( &'store self, operator: TextSelectionOperator, refset: &'q TextSelectionSet ) -> FindTextSelectionsIter<'store, 'q>

Apply a TextSelectionOperator to find text selections This is a low-level method. Use Self::find_textselections() instead.

pub fn textselections_by_operator<'store>( &'store self, operator: TextSelectionOperator, refset: TextSelectionSet ) -> FindTextSelectionsOwnedIter<'store>

pub fn find_textselections_ref<'store, 'q>( &'store self, operator: TextSelectionOperator, refset: &'q TextSelectionSet ) -> impl Iterator<Item = WrappedItem<'store, TextSelection>> + 'qwhere 'store: 'q,

Find textselections by applying a text selection operator (TextSelectionOperator) to a one or more querying textselections (in an [TextSelectionSet']). Returns an iterator over all matching text selections in the resource, as [WrappedItem`].

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

Find textselections by applying a text selection operator (TextSelectionOperator) to a one or more querying textselections (in an [TextSelectionSet']). Returns an iterator over all matching text selections in the resource, as [WrappedItem`].

Trait Implementations

impl AssociatedFile for TextResource

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) -> Selfwhere 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 TextResource

fn clone(&self) -> TextResource

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Configurable for TextResource

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 Debug for TextResource

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TextResource

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

Deserialize this value from the given Serde deserializer.

impl PartialEq<TextResource> for TextResource

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

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

Returns a selector to this resource

impl Serialize for TextResource

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 TextResource

type HandleType = TextResourceHandle

type StoreType = AnnotationStore

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

Get the public ID

fn handle(&self) -> Option<TextResourceHandle>

Retrieve the internal (numeric) id. For any type T uses in StoreFor<T>, this may be None only in the initial stage when it is still unbounded to a store.

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

Builder pattern to set the public Id

fn set_handle(&mut self, handle: TextResourceHandle)

Set the internal ID. May only be called once (though currently not enforced).

fn carries_id() -> bool

Does this type support an ID?

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 id_or_err(&self) -> Result<&str, StamError>

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

fn wrap_in<'store>( &'store self, store: &'store Self::StoreType ) -> Result<WrappedItem<'store, Self>, StamError>where Self: Sized,

Returns a wrapped reference to this item and the store that owns it. This allows for some more introspection on the part of the item. reverse of StoreFor<T>::wrap()

fn wrap_owned_in<'store>( self, store: &'store Self::StoreType ) -> Result<WrappedItem<'store, Self>, StamError>where Self: Sized,

Returns a wrapped reference to this item and the store that owns it. This allows for some more introspection on the part of the item. reverse of StoreFor<T>::wrap_owned()

fn bound(&mut self)

Callback function that is called after an item is bound to a store

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

Generate a random ID in a given idmap (adds it to the map and assigns it to the item)

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 StoreFor<TextSelection> for TextResource

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

Get a reference to the entire store for the associated type

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

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

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

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<TextSelectionHandle>>

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: TextSelectionHandle) -> 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 preremove(&mut self, handle: T::HandleType) -> Result<(), StamError>

Called before an item is removed from the store Allows the store to do further bookkeeping like updating relation maps

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<'store> Text<'store, 'store> for TextResource

fn textlen(&self) -> usize

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

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

Returns a reference to the full text of this resource

fn text_by_offset( &'store 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>

Resolves a begin aligne cursor to UTF-8 byteposition If you have a Cursor instance, pass it through [Self.beginaligned_cursor()] first.

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

Convert utf8 byte to unicode point. O(n), not as efficient as the reverse operation in [’utf8byte()`]

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

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

fn find_text_regex<'regex>( &'store 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>( &'store 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 [Self.find_text_nocase()] to search case insensitive. 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()` on that instead.

fn find_text_nocase(&'store 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 subslice_utf8_offset(&self, subslice: &str) -> Option<usize>

Finds the utf-8 byte position where the specified text subslice begins

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

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

fn split_text<'b>(&'store 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<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)

impl ToJson for TextResource

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 TryFrom<TextResourceBuilder> for TextResource

type Error = StamError

The type returned in the event of a conversion error.

fn try_from(builder: TextResourceBuilder) -> Result<Self, StamError>

Performs the conversion.

impl TypeInfo for TextResource

fn typeinfo() -> Type