Struct tendril::Tendril
[−]
[src]
pub struct Tendril<F, A = NonAtomic> where F: Format, A: Atomicity { // some fields omitted }
Compact string type for zero-copy parsing.
Tendril
s 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
[src]
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
[src]
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
[src]
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<F, A> Tendril<F, A> where A: Atomicity, F: SliceFormat<Slice=[u8]>
[src]
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
[src]
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
[src]
impl<F, A> Sync for Tendril<F, A> where F: Format, A: Atomicity + Sync
[src]
impl<F, A> Clone for Tendril<F, A> where F: Format, A: Atomicity
[src]
fn clone(&self) -> Tendril<F, A>
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl<F, A> Drop for Tendril<F, A> where F: Format, A: Atomicity
[src]
impl<A> Extend<char> for Tendril<UTF8, A> where A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=char>
Extends a collection with the contents of an iterator. Read more
impl<A> FromIterator<char> for Tendril<UTF8, A> where A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=char>
Creates a value from an iterator. Read more
impl<A> Extend<u8> for Tendril<Bytes, A> where A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=u8>
Extends a collection with the contents of an iterator. Read more
impl<A> FromIterator<u8> for Tendril<Bytes, A> where A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=u8>
Creates a value from an iterator. Read more
impl<'a, A> Extend<&'a u8> for Tendril<Bytes, A> where A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=&'a u8>
Extends a collection with the contents of an iterator. Read more
impl<'a, A> FromIterator<&'a u8> for Tendril<Bytes, A> where A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=&'a u8>
Creates a value from an iterator. Read more
impl<'a, A> Extend<&'a str> for Tendril<UTF8, A> where A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=&'a str>
Extends a collection with the contents of an iterator. Read more
impl<'a, A> FromIterator<&'a str> for Tendril<UTF8, A> where A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=&'a str>
Creates a value from an iterator. Read more
impl<'a, A> Extend<&'a [u8]> for Tendril<Bytes, A> where A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=&'a [u8]>
Extends a collection with the contents of an iterator. Read more
impl<'a, A> FromIterator<&'a [u8]> for Tendril<Bytes, A> where A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=&'a [u8]>
Creates a value from an iterator. Read more
impl<'a, F, A> Extend<&'a Tendril<F, A>> for Tendril<F, A> where F: Format + 'a, A: Atomicity
[src]
fn extend<I>(&mut self, iterable: I) where I: IntoIterator<Item=&'a Tendril<F, A>>
Extends a collection with the contents of an iterator. Read more
impl<'a, F, A> FromIterator<&'a Tendril<F, A>> for Tendril<F, A> where F: Format + 'a, A: Atomicity
[src]
fn from_iter<I>(iterable: I) -> Self where I: IntoIterator<Item=&'a Tendril<F, A>>
Creates a value from an iterator. Read more
impl<F, A> Deref for Tendril<F, A> where F: SliceFormat, A: Atomicity
[src]
type Target = F::Slice
The resulting type after dereferencing
fn deref(&self) -> &F::Slice
The method called to dereference a value
impl<F, A> DerefMut for Tendril<F, A> where F: SliceFormat, A: Atomicity
[src]
fn deref_mut(&mut self) -> &mut F::Slice
The method called to mutably dereference a value
impl<F, A> Borrow<[u8]> for Tendril<F, A> where F: SliceFormat, A: Atomicity
[src]
impl<F, A> PartialEq for Tendril<F, A> where F: Format, A: Atomicity
[src]
fn eq(&self, other: &Self) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Self) -> bool
This method tests for !=
.
impl<F, A> Eq for Tendril<F, A> where F: Format, A: Atomicity
[src]
impl<F, A> PartialOrd for Tendril<F, A> where F: SliceFormat, F::Slice: PartialOrd, A: Atomicity
[src]
fn partial_cmp(&self, other: &Self) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl<F, A> Ord for Tendril<F, A> where F: SliceFormat, F::Slice: Ord, A: Atomicity
[src]
fn cmp(&self, other: &Self) -> Ordering
This method returns an Ordering
between self
and other
. Read more
impl<F, A> Default for Tendril<F, A> where F: Format, A: Atomicity
[src]
impl<F, A> Debug for Tendril<F, A> where F: SliceFormat + Default + Debug, F::Slice: Debug, A: Atomicity
[src]
impl<F, A> Hash for Tendril<F, A> where F: Format, A: Atomicity
[src]
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
1.3.0
Feeds a slice of this type into the state provided.
impl<F, A> From<SendTendril<F>> for Tendril<F, A> where F: Format, A: Atomicity
[src]
fn from(send: SendTendril<F>) -> Tendril<F, A>
Performs the conversion.
impl<A> Write for Tendril<Bytes, A> where A: Atomicity
[src]
fn write(&mut self, buf: &[u8]) -> Result<usize>
Write a buffer into this object, returning how many bytes were written. Read more
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this write. Read more
fn flush(&mut self) -> Result<()>
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0
Writes a formatted string into this writer, returning any error encountered. Read more
fn by_ref(&mut self) -> &mut Self
1.0.0
Creates a "by reference" adaptor for this instance of Write
. Read more
impl<A> ByteWriter for Tendril<Bytes, A> where A: Atomicity
[src]
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. RawEncoder
s are recommended but not required to call this method with an appropriate estimate. By default this method does nothing. Read more
impl<A> Display for Tendril<UTF8, A> where A: Atomicity
[src]
impl<A> FromStr for Tendril<UTF8, A> where A: Atomicity
[src]
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. Read more
impl<A> Write for Tendril<UTF8, A> where A: Atomicity
[src]
fn write_str(&mut self, s: &str) -> Result
Writes a slice of bytes into this writer, returning whether the write succeeded. Read more
fn write_char(&mut self, c: char) -> Result<(), Error>
1.1.0
Writes a char
into this writer, returning whether the write succeeded. Read more
fn write_fmt(&mut self, args: Arguments) -> Result<(), Error>
1.0.0
Glue for usage of the write!
macro with implementors of this trait. Read more
impl<A> StringWriter for Tendril<UTF8, A> where A: Atomicity
[src]
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. RawDecoder
s are recommended but not required to call this method with an appropriate estimate. By default this method does nothing. Read more
impl<'a, F, A> From<&'a F::Slice> for Tendril<F, A> where F: SliceFormat, A: Atomicity
[src]
impl<A> From<String> for Tendril<UTF8, A> where A: Atomicity
[src]
impl<F, A> AsRef<F::Slice> for Tendril<F, A> where F: SliceFormat, A: Atomicity
[src]
fn as_ref(&self) -> &F::Slice
Performs the conversion.