Struct tendril::Tendril

pub struct Tendril<F, A = NonAtomic> where F: Format, A: Atomicity {
    // some 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 and Sync (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.

Methods

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

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

Create a new, empty Tendril in any format.

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

Create a new, empty Tendril with a specified capacity.

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.

fn len32(&self) -> u32

Get the length of the Tendril.

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

fn is_shared(&self) -> bool

Is the backing buffer shared?

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

Is the backing buffer shared with this other Tendril?

fn clear(&mut self)

Truncate to length 0 without discarding any owned storage.

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.

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

View as uninterpreted bytes.

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

Convert into uninterpreted bytes.

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.

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

View as a superset format, for free.

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

Convert into a superset format, for free.

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.

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.

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.

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.

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

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

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

Push another Tendril onto the end of this one.

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.

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

Slice this Tendril as a new Tendril.

Panics on bounds or validity check failure.

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.

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.

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.

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.

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

View as another format, without validating.

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

Convert into another format, without validating.

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

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

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

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

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!

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

Drop n bytes from the front.

Does not check validity or bounds!

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

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

Build a Tendril by copying a slice.

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

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

Remove and return the first character, if any.

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.

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

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

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

fn decode(&self, encoding: EncodingRef, trap: DecoderTrap) -> Result<Tendril<UTF8, A>, Cow<'static, str>>

Decode from some character encoding into UTF-8.

See the rust-encoding docs for more information.

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

fn encode(&self, encoding: EncodingRef, trap: EncoderTrap) -> Result<Tendril<Bytes, A>, Cow<'static, str>>

Encode from UTF-8 into some other character encoding.

See the rust-encoding docs for more information.

fn push_char(&mut self, c: char)

Push a character onto the end.

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

Create a Tendril from a single character.

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

Helper for the format_tendril! macro.

Trait Implementations

impl<F, A> Send for Tendril<F, A> where F: Format, A: Atomicity + Sync

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

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

fn drop(&mut self)

A method called when the value goes out of scope.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

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

Extends a collection with the contents of an iterator.

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

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

Creates a value from an iterator.

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

type Target = F::Slice

The resulting type after dereferencing

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

The method called to dereference a value

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

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

Immutably borrows from an owned value.

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

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

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

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

This method tests for !=.

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

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

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<F, A> Ord for Tendril<F, A> where F: SliceFormat, F::Slice: Ord, A: Atomicity

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

This method returns an Ordering between self and other.

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

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

Returns the "default value" for a type.

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

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

Formats the value using the given formatter.

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

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.

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

fn deref_mut<'a>(&'a mut self) -> &'a mut [u8]

The method called to mutably dereference a value

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

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

Performs the conversion.

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

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

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

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

Attempts to write an entire buffer into this write.

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

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

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

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

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

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

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

fn write_byte(&mut self, b: u8)

Writes a single byte.

fn write_bytes(&mut self, v: &[u8])

Writes a number of bytes.

fn writer_hint(&mut self, additional: usize)

Hints an expected lower bound on the length (in bytes) of the output until the next call to writer_hint, so that the writer can reserve the memory for writing. RawEncoders are recommended but not required to call this method with an appropriate estimate. By default this method does nothing.

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

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

Formats the value using the given formatter.

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

type Err = ()

The associated error which can be returned from parsing.

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

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

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

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

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

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

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

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

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

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

fn write_char(&mut self, c: char)

Writes a single character.

fn write_str(&mut self, s: &str)

Writes a string.

fn writer_hint(&mut self, additional: usize)

Hints an expected lower bound on the length (in bytes) of the output until the next call to writer_hint, so that the writer can reserve the memory for writing. RawDecoders are recommended but not required to call this method with an appropriate estimate. By default this method does nothing.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.