Struct tendril::tendril::Tendril[][src]

#[repr(C)]
pub struct Tendril<F, A = NonAtomic> where
    F: Format,
    A: Atomicity
{ ptr: Cell<NonZeroUsize>, buf: UnsafeCell<Buffer>, marker: PhantomData<*mut F>, refcount_marker: PhantomData<A>, }
Expand description

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.

Fields

ptr: Cell<NonZeroUsize>buf: UnsafeCell<Buffer>marker: PhantomData<*mut F>refcount_marker: PhantomData<A>

Implementations

Create a new, empty Tendril in any format.

Create a new, empty Tendril with a specified capacity.

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.

Reserve space for additional bytes, even for shared buffers.

Get the length of the Tendril.

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

Is the backing buffer shared?

Is the backing buffer shared with this other Tendril?

Truncate to length 0 without discarding any owned storage.

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

View as uninterpreted bytes.

Convert into uninterpreted bytes.

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.

View as a superset format, for free.

Convert into a superset format, for free.

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

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

View as another format, if the bytes of the Tendril are valid for that 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.

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

Push another Tendril onto the end of this one.

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.

Slice this Tendril as a new Tendril.

Panics on bounds or validity check failure.

Try to drop n bytes from the front.

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

Drop n bytes from the front.

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

Drop n bytes from the back.

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

Drop n bytes from the back.

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

View as another format, without validating.

Convert into another format, without validating.

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

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

Slice this Tendril as a new Tendril.

Does not check validity or bounds!

Drop n bytes from the front.

Does not check validity or bounds!

Drop n bytes from the back.

Does not check validity or bounds!

Build a Tendril by copying a slice.

Push a slice onto the end of the Tendril.

Remove and return the first character, if any.

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.

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

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.

Push a character onto the end.

Create a Tendril from a single character.

Helper for the format_tendril! macro.

Trait Implementations

Performs the conversion.

Immutably borrows from an owned value. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Extends a collection with the contents of an iterator. Read more

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

Extends a collection with exactly one element.

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

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

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

Creates a value from an iterator. Read more

The associated error which can be returned from parsing.

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

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

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

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

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

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

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

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

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

Attempts to write an entire buffer into this writer. Read more

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

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

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

Determines if this Writer has an efficient write_vectored implementation. Read more

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

Attempts to write multiple buffers into this writer. Read more

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

Creates a “by reference” adapter for this instance of Write. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

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

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.