[−][src]Trait kul_core::Text

pub trait Text: TextBase where
    Self: From<Self::Chunk>, {
    type Chunk: TextChunk<Pos = Self::Pos>;
    type IterChunksState: State<Chunk = Self::Chunk> + ?Sized;
    fn iter_chunks_state(&self) -> Option<&Self::IterChunksState>;

    fn from_chunkish<T>(v: T) -> Self
    where
        T: Into<Self::Chunk>,
    { ... }

    fn from_str<'s>(s: &'s str) -> Self
    where
        Self::Chunk: From<&'s str>,
    { ... }

    fn eq<O: Text>(&self, other: &O) -> bool { ... }

    fn cmp<O: Text>(&self, other: &O) -> Ordering { ... }

    fn hash<H: Hasher>(&self, state: &mut H) { ... }

    fn chars(&self) -> Chars<Self> { ... }

    fn encode_utf8<'b>(&self, buf: &'b mut [u8]) -> Result<&'b str, &'b str> { ... }

    fn iter_chunks(&self) -> Iter<Self> { ... }

    fn iter(&self) -> Iter<Self> { ... }
}

A logical sequence of characters, possibly represented as separate chunks, that can be iterated multiple times without consuming or destroying the source, and that might know its characters' positions in the source it is from.

Because Rust's generic_associated_types is not stable yet, this trait has a design that enables a somewhat-flexible interface for relating the lifetimes of borrows that enables different implementations of how the chunking is represented internally. This enables the iteration functionality to generically work with all types of this trait.

Types of this trait are required to be able to be constructed from a single chunk, which assists its use.

Associated Types

type Chunk: TextChunk<Pos = Self::Pos>

The type of underlying chunks used to represent our character sequence.

type IterChunksState: State<Chunk = Self::Chunk> + ?Sized

Enables generic flexibility in the internal representation of how chunks are held and chained, while also enabling the borrowing of references to this from the self so that the lifetimes are those of our method calls' borrows of self.

Loading content...

Required methods

fn iter_chunks_state(&self) -> Option<&Self::IterChunksState>

Return a borrow of our self's particular representation of chained chunks to be used by our special iterator types.

A None return means we have zero chunks (and so are logically empty), but a Some return with one or more chunks may also represent logical emptiness, and some types do canonically represent emptiness with at least one chunk.

Loading content...

Provided methods

fn from_chunkish<T>(v: T) -> Self where
    T: Into<Self::Chunk>, 

Make an instance of our Self from anything that can convert into a single chunk of our Chunk type.

fn from_str<'s>(s: &'s str) -> Self where
    Self::Chunk: From<&'s str>, 

Make an instance of our Self from a &str slice, if our Chunk type can convert from that.

fn eq<O: Text>(&self, other: &O) -> bool

Equality comparison with any other type of Text. Compares the logical sequences of chars.

Useful here because PartialEq and Eq cannot be blanket-implemented between all generic Text types. The default implementation uses our special iterator type to enable comparing across arbitrary, often inconsistent, chunk boundaries.

This is a full equivalence relation.

fn cmp<O: Text>(&self, other: &O) -> Ordering

Ordering comparison with any other type of Text. Compares the logical sequences of chars lexicographically.

Useful here because PartialOrd and Ord cannot be blanket-implemented between all generic Text types. The default implementation uses our special iterator type to enable comparing across arbitrary, often inconsistent, chunk boundaries.

This is a total ordering relation.

fn hash<H: Hasher>(&self, state: &mut H)

Hash the logical sequence of chars.

The default implementation uses our special iterator type to enable hashing across arbitrary, often inconsistent, chunk boundaries.

fn chars(&self) -> Chars<Self>

Construct a new iterator that yields the logical character sequence of the given self.

The default implementation uses our special iterator type to enable yielding characters across arbitrary, often inconsistent, chunk boundaries.

fn encode_utf8<'b>(&self, buf: &'b mut [u8]) -> Result<&'b str, &'b str>

Encode the logical character sequence of the given self as UTF-8 into the provided byte buffer. If the buffer is large enough to contain all the characters, then return the subslice of the buffer that contains them all, as an Ok. If the buffer is too small, then return the subslice that contains as many as fit (which might be shorter than the provided buffer), as an Err.

This is intended for no_std constrained applications where String is unavailable. When it is available, instead of this function, it is probably more desirable to use: String::from_iter(self.chars()).

The default implementation uses our special iterator type to get the characters across arbitrary, often inconsistent, chunk boundaries.

ⓘImportant traits for Iter<'l, TT>
fn iter_chunks(&self) -> Iter<Self>

Construct a new iterator that yields borrows of each of our underlying chunks.

Used by both the special text::iter::Iter and by some other things that want to process each chunk.

ⓘImportant traits for Iter<'l, TT>
fn iter(&self) -> Iter<Self>

Construct a new iterator, which is also a kul_core::SourceStream if the Self type is also a TextConcat, that yields the logical character sequence, and their positions, of the given self.

The returned text::Iter type is parameterized over the same lifetime as the borrows of self of calls of this method, which enables it to contain borrows derived from a self borrow, which is essential.

This is how the correct lifetime relating is achieved without generic asssociated types. If/when the generic_associated_types feature becomes available in stable Rust, our design should probably be redone to leverage that feature for a cleaner design.

Loading content...

Implementors

impl<C, ET, '_> Text for TextDatumList<'_, C, ET> where
    C: TextChunk, [src]

type Chunk = C

type IterChunksState = Self

fn from_chunkish<T>(v: T) -> Self where
    T: Into<Self::Chunk>, [src]

fn from_str<'s>(s: &'s str) -> Self where
    Self::Chunk: From<&'s str>, [src]

fn eq<O: Text>(&self, other: &O) -> bool[src]

fn cmp<O: Text>(&self, other: &O) -> Ordering[src]

fn hash<H: Hasher>(&self, state: &mut H)[src]

fn chars(&self) -> Chars<Self>[src]

fn encode_utf8<'b>(&self, buf: &'b mut [u8]) -> Result<&'b str, &'b str>[src]

ⓘImportant traits for Iter<'l, TT>
fn iter_chunks(&self) -> Iter<Self>[src]

ⓘImportant traits for Iter<'l, TT>
fn iter(&self) -> Iter<Self>[src]

Loading content...