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 to_json_string(&self) -> Result<String, StamError>

Writes a Resource to one big STAM JSON string, with appropriate formatting If the actual data is in a stand-off file, this will be written to as well.

impl TextResource

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

Instantiates a new completely empty TextResource

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_string(self, text: impl Into<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: impl Into<String>, text: impl Into<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 FindText::textselection() instead if you want to return a textselection regardless of whether it’s known or not.

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

Low-level method to get a textselection, if the text selection is known, its’ handle will be set If you don’t care about unbound textselection but only known ones, then use Self::known_textselection() instead.

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

Low-level method returning 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 (in order) 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_unsorted() 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 positions_in_range<'a>( &'a self, mode: PositionMode, begin: usize, end: usize ) -> Box<dyn Iterator<Item = &'a usize> + 'a>

Returns a sorted iterator over all absolute positions (begin aligned cursors) that are in use within a certain range. 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

pub fn positionindex_iter(&self) -> Iter<'_, usize, PositionIndexItem>

Returns a low-level iterator over the position index

pub fn meminfo(&self) -> usize

Returns a lower-bound estimate of memory usage in bytes

pub fn shrink_to_fit(&mut self)

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) -> 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 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 DataSize for TextResource

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 TextResource

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

Formats the value using the given formatter.

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

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

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 PartialEq 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 PartialOrd for TextResource

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> Request<TextResource> for TextResourceHandle

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

where S: StoreFor<TextResource>,

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

fn to_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 StoreHandleType = ()

type FullHandleType = <TextResource as Storable>::HandleType

type StoreType = AnnotationStore

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

Get the public identifier

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

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_id(self, id: impl Into<String>) -> Self

Builder pattern to set the public ID

fn with_handle(self, handle: TextResourceHandle) -> 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 merge(&mut self, other: Self) -> Result<(), StamError>

Merge another item into this one This is a low-level API method, mostly for internal use.

fn unbind(self) -> Self

Unbind an item This is a low-level API method that can not be used publicly due to ownership restrictions.

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

Removes an item

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

Removes an item

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<'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 Self::utf8byte()

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 is_empty(&'slf self) -> bool

fn absolute_offset(&'slf 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)

fn beginaligned_cursor(&'slf self, cursor: &Cursor) -> Result<usize, StamError>

Resolves a cursor to a begin aligned cursor, resolving all relative end-aligned positions

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

Return the type (introspection).

fn temp_id_prefix() -> &'static str

Return the prefix for temporary identifiers of this type