Struct kul::text::chunk::PosStrish

pub struct PosStrish<S> {
    pub val: RefCntSlice<S>,
    pub pos: CharPos,
}

A TextChunk implementation for boxed (heap allocated) string values, termed "string-ish" throughout this crate, used distinctly as chunks. This is useful for strings produced from streaming sources that buffered into one or more strings separated at possibly arbitrary points.

This is designed to generically support various boxed string types with shared ownership, e.g. Rc<String>, Arc<str>, Rc<Box<str>>, termed "reference-counted string-ish" types. The set of such types allowed is those types that already implement the sealed RefCntStrish trait. This design allows users to choose what trade-offs of convenience and efficiency they want between these allowed types. Shared ownership, i.e. Rc or Arc, is required because this avoids copying string contents, achieving zero-copy operations, once initially buffered or copied into a reference-counted string-ish, i.e. RefCntStrish-implementing, value.

The character position information this provides is only the position of each char relative to the start of the stream, because this does not concern itself with what byte encoding or other position information, if any, the streamed source might have had.

This is not intended for streaming sources that have richer position information that is desired to be preserved. For those, a dedicated implementation of TextChunk should be made instead.

This is not intended for single string values that are an entire input for parsing. For that, PosStr (as the Chunk type of some Text type) should be used instead because it provides faster zero-copy operations as well as byte position information.

Note: The comparison traits are not implemented intentionally, because this is intended as a chunk type and comparing those directly shouldn't be done.

Fields

val: RefCntSlice<S>

The represented heap-allocated string. The RefCntSlice type is private but it implements AsRef<str> and so can be used as &str.

pos: CharPos

The char position of the start of our string relative to its original source.

Methods

impl<S> PosStrish<S> where
    S: RefCntStrish, 

pub fn new(refcnt_strish: S, pos: CharPos) -> Self

Given an Rc- or Arc-boxed string and its position relative to its original source, make a new chunk that represents this and can be used with Text types.

Trait Implementations

impl<'s, S> From<&'s str> for PosStrish<S> where
    S: RefCntStrish, 

fn from(val: &'s str) -> Self

Performs the conversion.

impl<S: Clone> Clone for PosStrish<S>

fn clone(&self) -> PosStrish<S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S: Debug> Debug for PosStrish<S>

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

Formats the value using the given formatter.

impl<S> TextChunk for PosStrish<S> where
    S: RefCntStrish, 

type CharsSrcStrm = PosStrishIter<S>

Our chunk::SourceStream type.

fn src_strm(&self) -> Self::CharsSrcStrm

Construct a new iterator, which is also a chunk::SourceStream, that yields the character sequence, and their positions, of the given self chunk.

impl<S> SourceStream<PosStrish<S>> for PosStrishIter<S> where
    S: RefCntStrish, 

Enables PosStrish to be used as the Chunk type of Text types that implement TextConcat so they can be iterated with kul_core::SourceStream. A chunk::SourceStream can accumulate what it iterates within a single chunk. This records and grows a slice range and creates a new chunk representing that, which shares ownership of the original string, for each accumulation, which is zero-copy.

fn peek(&mut self) -> Option<&Self::Item>

Returns a reference to the next item's value without advancing the iterator and without interfering with any pending accumulation.

fn next_accum(&mut self) -> Option<Self::Item>

Get the next item, if any, and add it to a pending, or start a new, accumulation, and return the item.

fn accum_done(&mut self) -> PosStrish<S>

Take any pending accumulation and return it as a new chunk, or return an empty chunk if there was nothing pending.

impl<S> TextBase for PosStrish<S> where
    S: RefCntStrish, 

type Pos = CharPos

Positional information used with our chunks and chars.

fn empty() -> Self

Make an empty one.

fn is_empty(&self) -> bool

Predicate for if an instance is an empty one.