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) -> Self

Instantiates a new completely empty TextResource

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

Builds a new text resource from [`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

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

Writes a resource to a STAM JSON file, with appropriate formatting

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

Writes a resource to a STAM JSON file, without any indentation

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

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

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

Writes a resource to a STAM JSON string, without any indentation

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

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

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

Sets the text of the TextResource from string, kept in memory entirely

pub fn textlen(&self) -> usize

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

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

Create a new TextResource from string, kept in memory entirely

pub fn text(&self) -> &str

Returns a reference to the full text of this resource

pub fn textselection(&self, offset: &Offset) -> Result<TextSelection, StamError>

Returns a [TextSelection'] that corresponds to the offset. If the TextSelection exists, the existing one will be returned (as a copy, but it will have a TextSelection.handle()`). 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.

Use [find_textselection()] instead if you want to limit to existing text selections only.

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

Finds an existing text selection**, as specified by the offset. Returns a handle. by the offset. Use the higher-level method [Self.textselection()] instead if you in most circumstances.

pub fn text_slice(&self, offset: &Offset) -> Result<&str, StamError>

Returns a string reference to a slice of text as specified by the offset This is a higher-level variant of [Self.text_by_textselection()].

pub fn text_by_textselection( &self, selection: &TextSelection ) -> Result<&str, StamError>

Returns the text for a given TextSelection. Make sure the TextSelection applies to this resource, there are no further checks here. Use [Self.text_slice()] for a higher-level method that takes an offset.

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

Resolves a cursor to an absolute position (by definition begin aligned)

pub fn utf8byte(&self, abscursor: usize) -> Result<usize, StamError>

Resolves an absolute cursor (by definition begin aligned) to UTF-8 byteposition If you have a Cursor instance, pass it through [Self.absolute_cursor()] first.

pub 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()`]

pub fn search_text<'a, 'b>( &'a self, expressions: &'b [Regex], offset: Option<&Offset>, precompiledset: Option<&RegexSet> ) -> Result<SearchTextIter<'a, 'b>, 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 [`SearchTextMatch’] 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 experssion is returned. An offset can be specified to work on a sub-part rather than the entire text (like an existing TextSelection).

pub fn text_selector( &self, begin: Cursor, end: Cursor ) -> Result<Selector, StamError>

Returns a text selector with the specified offset in this resource

pub fn textselections(&self) -> Box<impl Iterator<Item = &TextSelection>>

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

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

Trait Implementations

impl Configurable for TextResource

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

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, 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<'a, S: StoreFor<Self>>( &'a self, store: &'a S ) -> Result<WrappedStorable<'_, Self, S>, 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 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 introspect_type(&self) -> &'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 contains(&self, item: &T) -> bool

Returns true if the store contains the item

fn find(&self, item: &T) -> Option<T::HandleType>

Retrieves the internal id for the item as it occurs in the store. The passed item and reference item may be distinct instances.

fn has(&self, handle: T::HandleType) -> bool

Returns true if the store has the item with the specified internal id

fn has_id(&self, id: &str) -> bool

Returns true if the store has the item with the specified global id

fn get_by_id<'a>(&'a self, id: &str) -> Result<&'a T, StamError>

Get a reference to an item from the store by its global ID

fn get_mut_by_id<'a>(&'a mut self, id: &str) -> Result<&'a mut T, StamError>

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

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

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

fn get_mut(&mut self, handle: T::HandleType) -> 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>

Iterate over the store

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

Iterate over the store, mutably

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

Get the item from the store if it already exists, if not, add it

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 get_by_anyid(&self, anyid: &AnyId<T::HandleType>) -> Option<&T>

Get a reference to an item from the store by any ID The advantage of AnyId is that you can coerce strings, references and handles to it using into(). If the item does not exist, None will be returned

fn get_by_anyid_or_err( &self, anyid: &AnyId<T::HandleType> ) -> Result<&T, StamError>

Get a reference to an item from the store by any ID. Returns an error on failure. The advantage of AnyId is that you can coerce strings, references and handles to it using into(). If the item does not exist, None will be returned

fn get_mut_by_anyid(&mut self, anyid: &AnyId<T::HandleType>) -> Option<&mut T>

Get a reference to an item from the store by any ID If the item does not exist, None will be returned

fn wrap<'a>( &'a self, item: &'a T ) -> Result<WrappedStorable<'_, T, Self>, StamError>where Self: Sized,

Wraps the reference with a reference to the store

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

Wraps the entire store along with a reference to self

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 introspect_type(&self) -> &'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 contains(&self, item: &T) -> bool

Returns true if the store contains the item

fn find(&self, item: &T) -> Option<T::HandleType>

Retrieves the internal id for the item as it occurs in the store. The passed item and reference item may be distinct instances.

fn has(&self, handle: T::HandleType) -> bool

Returns true if the store has the item with the specified internal id

fn has_id(&self, id: &str) -> bool

Returns true if the store has the item with the specified global id

fn get_by_id<'a>(&'a self, id: &str) -> Result<&'a T, StamError>

Get a reference to an item from the store by its global ID

fn get_mut_by_id<'a>(&'a mut self, id: &str) -> Result<&'a mut T, StamError>

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

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

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

fn get_mut(&mut self, handle: T::HandleType) -> 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>

Iterate over the store

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

Iterate over the store, mutably

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

Get the item from the store if it already exists, if not, add it

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 get_by_anyid(&self, anyid: &AnyId<T::HandleType>) -> Option<&T>

Get a reference to an item from the store by any ID The advantage of AnyId is that you can coerce strings, references and handles to it using into(). If the item does not exist, None will be returned

fn get_by_anyid_or_err( &self, anyid: &AnyId<T::HandleType> ) -> Result<&T, StamError>

Get a reference to an item from the store by any ID. Returns an error on failure. The advantage of AnyId is that you can coerce strings, references and handles to it using into(). If the item does not exist, None will be returned

fn get_mut_by_anyid(&mut self, anyid: &AnyId<T::HandleType>) -> Option<&mut T>

Get a reference to an item from the store by any ID If the item does not exist, None will be returned

fn wrap<'a>( &'a self, item: &'a T ) -> Result<WrappedStorable<'_, T, Self>, StamError>where Self: Sized,

Wraps the reference with a reference to the store

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

Wraps the entire store along with a reference to self

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.