Struct tendril::Tendril

#[repr(C)]pub struct Tendril<F, A = NonAtomic> where
    F: Format,
    A: Atomicity,  { /* fields omitted */ }

Compact string type for zero-copy parsing.

Tendrils have the semantics of owned strings, but are sometimes views into shared buffers. When you mutate a Tendril, an owned copy is made if necessary. Further mutations occur in-place until the string becomes shared, e.g. with clone() or subtendril().

Buffer sharing is accomplished through thread-local (non-atomic) reference counting, which has very low overhead. The Rust type system will prevent you at compile time from sending a Tendril between threads. We plan to relax this restriction in the future; see README.md.

Whereas String allocates in the heap for any non-empty string, Tendril can store small strings (up to 8 bytes) in-line, without a heap allocation. Tendril is also smaller than String on 64-bit platforms — 16 bytes versus 24.

The type parameter F specifies the format of the tendril, for example UTF-8 text or uninterpreted bytes. The parameter will be instantiated with one of the marker types from tendril::fmt. See the StrTendril and ByteTendril type aliases for two examples.

The type parameter A indicates the atomicity of the tendril; it is by default NonAtomic, but can be specified as Atomic to get a tendril which implements Send (viz. a thread-safe tendril).

The maximum length of a Tendril is 4 GB. The library will panic if you attempt to go over the limit.

Implementations

impl<F, A> Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn new() -> Tendril<F, A>

Create a new, empty Tendril in any format.

pub fn with_capacity(capacity: u32) -> Tendril<F, A>

Create a new, empty Tendril with a specified capacity.

pub fn reserve(&mut self, additional: u32)

Reserve space for additional bytes.

This is only a suggestion. There are cases where Tendril will decline to allocate until the buffer is actually modified.

pub fn len32(&self) -> u32

Get the length of the Tendril.

This is named not to conflict with len() on the underlying slice, if any.

pub fn is_shared(&self) -> bool

Is the backing buffer shared?

pub fn is_shared_with(&self, other: &Tendril<F, A>) -> bool

Is the backing buffer shared with this other Tendril?

pub fn clear(&mut self)

Truncate to length 0 without discarding any owned storage.

pub fn try_from_byte_slice(x: &[u8]) -> Result<Tendril<F, A>, ()>

Build a Tendril by copying a byte slice, if it conforms to the format.

pub fn as_bytes(&self) -> &Tendril<Bytes, A>

View as uninterpreted bytes.

pub fn into_bytes(self) -> Tendril<Bytes, A>

Convert into uninterpreted bytes.

pub fn into_send(self) -> SendTendril<F>

Convert self into a type which is Send.

If the tendril is owned or inline, this is free, but if it's shared this will entail a copy of the contents.

pub fn as_superset<Super>(&self) -> &Tendril<Super, A> where
    F: SubsetOf<Super>,
    Super: Format, 

View as a superset format, for free.

pub fn into_superset<Super>(self) -> Tendril<Super, A> where
    F: SubsetOf<Super>,
    Super: Format, 

Convert into a superset format, for free.

pub fn try_as_subset<Sub>(&self) -> Result<&Tendril<Sub, A>, ()> where
    Sub: SubsetOf<F>, 

View as a subset format, if the Tendril conforms to that subset.

pub fn try_into_subset<Sub>(self) -> Result<Tendril<Sub, A>, Self> where
    Sub: SubsetOf<F>, 

Convert into a subset format, if the Tendril conforms to that subset.

pub fn try_reinterpret_view<Other>(&self) -> Result<&Tendril<Other, A>, ()> where
    Other: Format, 

View as another format, if the bytes of the Tendril are valid for that format.

pub fn try_reinterpret<Other>(self) -> Result<Tendril<Other, A>, Self> where
    Other: Format, 

Convert into another format, if the Tendril conforms to that format.

This only re-validates the existing bytes under the new format. It will not change the byte content of the tendril!

See the encode and decode methods for character encoding conversion.

pub fn try_push_bytes(&mut self, buf: &[u8]) -> Result<(), ()>

Push some bytes onto the end of the Tendril, if they conform to the format.

pub fn push_tendril(&mut self, other: &Tendril<F, A>)

Push another Tendril onto the end of this one.

pub fn try_subtendril(
    &self,
    offset: u32,
    length: u32
) -> Result<Tendril<F, A>, SubtendrilError>

Attempt to slice this Tendril as a new Tendril.

This will share the buffer when possible. Mutating a shared buffer will copy the contents.

The offset and length are in bytes. The function will return Err if these are out of bounds, or if the resulting slice does not conform to the format.

pub fn subtendril(&self, offset: u32, length: u32) -> Tendril<F, A>

Slice this Tendril as a new Tendril.

Panics on bounds or validity check failure.

pub fn try_pop_front(&mut self, n: u32) -> Result<(), SubtendrilError>

Try to drop n bytes from the front.

Returns Err if the bytes are not available, or the suffix fails validation.

pub fn pop_front(&mut self, n: u32)

Drop n bytes from the front.

Panics if the bytes are not available, or the suffix fails validation.

pub fn try_pop_back(&mut self, n: u32) -> Result<(), SubtendrilError>

Drop n bytes from the back.

Returns Err if the bytes are not available, or the prefix fails validation.

pub fn pop_back(&mut self, n: u32)

Drop n bytes from the back.

Panics if the bytes are not available, or the prefix fails validation.

pub unsafe fn reinterpret_view_without_validating<Other>(
    &self
) -> &Tendril<Other, A> where
    Other: Format, 

View as another format, without validating.

pub unsafe fn reinterpret_without_validating<Other>(self) -> Tendril<Other, A> where
    Other: Format, 

Convert into another format, without validating.

pub unsafe fn from_byte_slice_without_validating(x: &[u8]) -> Tendril<F, A>

Build a Tendril by copying a byte slice, without validating.

pub unsafe fn push_bytes_without_validating(&mut self, buf: &[u8])

Push some bytes onto the end of the Tendril, without validating.

pub unsafe fn unsafe_subtendril(
    &self,
    offset: u32,
    length: u32
) -> Tendril<F, A>

Slice this Tendril as a new Tendril.

Does not check validity or bounds!

pub unsafe fn unsafe_pop_front(&mut self, n: u32)

Drop n bytes from the front.

Does not check validity or bounds!

pub unsafe fn unsafe_pop_back(&mut self, n: u32)

Drop n bytes from the back.

Does not check validity or bounds!

impl<F, A> Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

pub fn from_slice(x: &F::Slice) -> Tendril<F, A>

Build a Tendril by copying a slice.

pub fn push_slice(&mut self, x: &F::Slice)

Push a slice onto the end of the Tendril.

impl<F, A> Tendril<F, A> where
    F: for<'a> CharFormat<'a>,
    A: Atomicity, 

pub fn pop_front_char<'a>(&'a mut self) -> Option<char>

Remove and return the first character, if any.

pub fn pop_front_char_run<'a, C, R>(
    &'a mut self,
    classify: C
) -> Option<(Tendril<F, A>, R)> where
    C: FnMut(char) -> R,
    R: PartialEq, 

Remove and return a run of characters at the front of the Tendril which are classified the same according to the function classify.

Returns None on an empty string.

pub fn try_push_char(&mut self, c: char) -> Result<(), ()>

Push a character, if it can be represented in this format.

impl<F, A> Tendril<F, A> where
    A: Atomicity,
    F: SliceFormat<Slice = [u8]>, 

pub unsafe fn push_uninitialized(&mut self, n: u32)

Push "uninitialized bytes" onto the end.

Really, this grows the tendril without writing anything to the new area. It's only defined for byte tendrils because it's only useful if you plan to then mutate the buffer.

impl<A> Tendril<UTF8, A> where
    A: Atomicity, 

pub fn push_char(&mut self, c: char)

Push a character onto the end.

pub fn from_char(c: char) -> Tendril<UTF8, A>

Create a Tendril from a single character.

pub fn format(args: Arguments<'_>) -> Tendril<UTF8, A>

Helper for the format_tendril! macro.

impl<A> Tendril<Bytes, A> where
    A: Atomicity, 

pub fn decode_utf8_lossy<F>(self, push_utf8: F) -> Option<IncompleteUtf8> where
    F: FnMut(Tendril<UTF8, A>), 

Trait Implementations

impl<F, A> AsRef<<F as SliceFormat>::Slice> for Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

pub fn as_ref(&self) -> &F::Slice

Performs the conversion.

impl<F, A> Borrow<[u8]> for Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

pub fn borrow(&self) -> &[u8]

Immutably borrows from an owned value.

impl<F, A> Clone for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn clone(&self) -> Tendril<F, A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F, A> Debug for Tendril<F, A> where
    F: SliceFormat + Default + Debug,
    <F as SliceFormat>::Slice: Debug,
    A: Atomicity, 

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

Formats the value using the given formatter.

impl<F, A> Default for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn default() -> Tendril<F, A>

Returns the "default value" for a type.

impl<F, A> Deref for Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

type Target = F::Slice

The resulting type after dereferencing.

pub fn deref(&self) -> &F::Slice

Dereferences the value.

impl<F, A> DerefMut for Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

pub fn deref_mut(&mut self) -> &mut F::Slice

Mutably dereferences the value.

impl<A> Display for Tendril<UTF8, A> where
    A: Atomicity, 

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

Formats the value using the given formatter.

impl<F, A> Drop for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn drop(&mut self)

Executes the destructor for this type.

impl<F, A> Eq for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

impl<'a, A> Extend<&'a [u8]> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = &'a [u8]>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, F, A> Extend<&'a Tendril<F, A>> for Tendril<F, A> where
    F: Format + 'a,
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = &'a Tendril<F, A>>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, A> Extend<&'a str> for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = &'a str>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, A> Extend<&'a u8> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = &'a u8>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<A> Extend<char> for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = char>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<A> Extend<u8> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn extend<I>(&mut self, iterable: I) where
    I: IntoIterator<Item = u8>, 

Extends a collection with the contents of an iterator.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, F, A> From<&'a <F as SliceFormat>::Slice> for Tendril<F, A> where
    F: SliceFormat,
    A: Atomicity, 

pub fn from(input: &F::Slice) -> Tendril<F, A>

Performs the conversion.

impl<'a, A> From<&'a Tendril<UTF8, A>> for String where
    A: Atomicity, 

pub fn from(input: &'a Tendril<UTF8, A>) -> String

Performs the conversion.

impl<F, A> From<SendTendril<F>> for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn from(send: SendTendril<F>) -> Tendril<F, A>

Performs the conversion.

impl<A> From<String> for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn from(input: String) -> Tendril<UTF8, A>

Performs the conversion.

impl<F, A> From<Tendril<F, A>> for SendTendril<F> where
    F: Format,
    A: Atomicity, 

pub fn from(tendril: Tendril<F, A>) -> SendTendril<F>

Performs the conversion.

impl<A> From<Tendril<UTF8, A>> for String where
    A: Atomicity, 

pub fn from(input: Tendril<UTF8, A>) -> String

Performs the conversion.

impl<'a, A> FromIterator<&'a [u8]> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = &'a [u8]>, 

Creates a value from an iterator.

impl<'a, F, A> FromIterator<&'a Tendril<F, A>> for Tendril<F, A> where
    F: Format + 'a,
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = &'a Tendril<F, A>>, 

Creates a value from an iterator.

impl<'a, A> FromIterator<&'a str> for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = &'a str>, 

Creates a value from an iterator.

impl<'a, A> FromIterator<&'a u8> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = &'a u8>, 

Creates a value from an iterator.

impl<A> FromIterator<char> for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = char>, 

Creates a value from an iterator.

impl<A> FromIterator<u8> for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn from_iter<I>(iterable: I) -> Self where
    I: IntoIterator<Item = u8>, 

Creates a value from an iterator.

impl<A> FromStr for Tendril<UTF8, A> where
    A: Atomicity, 

type Err = ()

The associated error which can be returned from parsing.

pub fn from_str(s: &str) -> Result<Self, ()>

Parses a string s to return a value of this type.

impl<F, A> Hash for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

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

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<F, A> Ord for Tendril<F, A> where
    F: SliceFormat,
    <F as SliceFormat>::Slice: Ord,
    A: Atomicity, 

pub fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<F, A> PartialEq<Tendril<F, A>> for Tendril<F, A> where
    F: Format,
    A: Atomicity, 

pub fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Self) -> bool

This method tests for !=.

impl<F, A> PartialOrd<Tendril<F, A>> for Tendril<F, A> where
    F: SliceFormat,
    <F as SliceFormat>::Slice: PartialOrd,
    A: Atomicity, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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<F, A> Send for Tendril<F, A> where
    F: Format,
    A: Atomicity + Sync, 

impl<A> Write for Tendril<UTF8, A> where
    A: Atomicity, 

pub fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

pub fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

pub fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl<A> Write for Tendril<Bytes, A> where
    A: Atomicity, 

pub fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

pub fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

pub fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

pub fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

pub fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

pub fn write_all_vectored(
    &mut self,
    bufs: &mut [IoSlice<'_>]
) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.