[−]Struct xml5ever::tendril::Tendril
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
(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
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
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,
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,
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>,
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>, Tendril<F, A>> where
Sub: SubsetOf<F>,
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,
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>, Tendril<F, A>> where
Other: Format,
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>
&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,
&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,
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>
&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
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
pub fn from_slice(x: &<F as SliceFormat>::Slice) -> Tendril<F, A>
Build a Tendril
by copying a slice.
pub fn push_slice(&mut self, x: &<F as SliceFormat>::Slice)
Push a slice onto the end of the Tendril
.
impl<F, A> Tendril<F, A> where
A: Atomicity,
F: CharFormat<'a>,
A: Atomicity,
F: CharFormat<'a>,
pub fn pop_front_char(&'a mut self) -> Option<char>
Remove and return the first character, if any.
pub fn pop_front_char_run<C, R>(
&'a mut self,
classify: C
) -> Option<(Tendril<F, A>, R)> where
C: FnMut(char) -> R,
R: PartialEq<R>,
&'a mut self,
classify: C
) -> Option<(Tendril<F, A>, R)> where
C: FnMut(char) -> R,
R: PartialEq<R>,
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]>,
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,
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,
A: Atomicity,
pub fn decode_utf8_lossy<F>(self, push_utf8: F) -> Option<IncompleteUtf8> where
F: FnMut(Tendril<UTF8, A>),
F: FnMut(Tendril<UTF8, A>),
Trait Implementations
impl<F, A> Hash for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
fn hash<H>(&self, hasher: &mut H) where
H: Hasher,
H: Hasher,
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl<A> From<String> for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
impl<F, A> From<SendTendril<F>> for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
fn from(send: SendTendril<F>) -> Tendril<F, A>
impl<F, A> From<Tendril<F, A>> for SendTendril<F> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
fn from(tendril: Tendril<F, A>) -> SendTendril<F>
impl<'a, F, A> From<&'a <F as SliceFormat>::Slice> for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
impl<'a, A> FromIterator<&'a [u8]> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
impl<'a, A> FromIterator<&'a u8> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn from_iter<I>(iterable: I) -> Tendril<Bytes, A> where
I: IntoIterator<Item = &'a u8>,
I: IntoIterator<Item = &'a u8>,
impl<'a, A> FromIterator<&'a str> for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
fn from_iter<I>(iterable: I) -> Tendril<UTF8, A> where
I: IntoIterator<Item = &'a str>,
I: IntoIterator<Item = &'a str>,
impl<'a, F, A> FromIterator<&'a Tendril<F, A>> for Tendril<F, A> where
A: Atomicity,
F: Format + 'a,
A: Atomicity,
F: Format + 'a,
fn from_iter<I>(iterable: I) -> Tendril<F, A> where
I: IntoIterator<Item = &'a Tendril<F, A>>,
I: IntoIterator<Item = &'a Tendril<F, A>>,
impl<A> FromIterator<char> for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
fn from_iter<I>(iterable: I) -> Tendril<UTF8, A> where
I: IntoIterator<Item = char>,
I: IntoIterator<Item = char>,
impl<A> FromIterator<u8> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn from_iter<I>(iterable: I) -> Tendril<Bytes, A> where
I: IntoIterator<Item = u8>,
I: IntoIterator<Item = u8>,
impl<F, A> AsRef<<F as SliceFormat>::Slice> for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
fn as_ref(&self) -> &<F as SliceFormat>::Slice
impl<F, A> Debug for Tendril<F, A> where
A: Atomicity,
F: SliceFormat + Default + Debug,
<F as SliceFormat>::Slice: Debug,
A: Atomicity,
F: SliceFormat + Default + Debug,
<F as SliceFormat>::Slice: Debug,
impl<A> Display for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
impl<F, A> Send for Tendril<F, A> where
A: Atomicity + Sync,
F: Format,
A: Atomicity + Sync,
F: Format,
impl<F, A> Borrow<[u8]> for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
impl<F, A> Clone for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
fn clone(&self) -> Tendril<F, A>
fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl<A> FromStr for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
type Err = ()
The associated error which can be returned from parsing.
fn from_str(s: &str) -> Result<Tendril<UTF8, A>, ()>
impl<F, A> PartialEq<Tendril<F, A>> for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
impl<F, A> Eq for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
impl<A> Write for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn flush(&mut self) -> Result<(), Error>
fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>
1.36.0[src]
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0[src]
fn by_ref(&mut self) -> &mut Self
1.0.0[src]
impl<A> Write for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
fn write_str(&mut self, s: &str) -> Result<(), Error>
fn write_char(&mut self, c: char) -> Result<(), Error>
1.1.0[src]
fn write_fmt(&mut self, args: Arguments) -> Result<(), Error>
1.0.0[src]
impl<F, A> Deref for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
type Target = <F as SliceFormat>::Slice
The resulting type after dereferencing.
fn deref(&self) -> &<F as SliceFormat>::Slice
impl<'a, A> Extend<&'a str> for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = &'a str>,
I: IntoIterator<Item = &'a str>,
impl<'a, A> Extend<&'a [u8]> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = &'a [u8]>,
I: IntoIterator<Item = &'a [u8]>,
impl<'a, A> Extend<&'a u8> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = &'a u8>,
I: IntoIterator<Item = &'a u8>,
impl<A> Extend<u8> for Tendril<Bytes, A> where
A: Atomicity,
A: Atomicity,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = u8>,
I: IntoIterator<Item = u8>,
impl<'a, F, A> Extend<&'a Tendril<F, A>> for Tendril<F, A> where
A: Atomicity,
F: Format + 'a,
A: Atomicity,
F: Format + 'a,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = &'a Tendril<F, A>>,
I: IntoIterator<Item = &'a Tendril<F, A>>,
impl<A> Extend<char> for Tendril<UTF8, A> where
A: Atomicity,
A: Atomicity,
fn extend<I>(&mut self, iterable: I) where
I: IntoIterator<Item = char>,
I: IntoIterator<Item = char>,
impl<F, A> Drop for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
fn drop(&mut self)
impl<F, A> DerefMut for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
A: Atomicity,
F: SliceFormat,
fn deref_mut(&mut self) -> &mut <F as SliceFormat>::Slice
impl<F, A> Default for Tendril<F, A> where
A: Atomicity,
F: Format,
A: Atomicity,
F: Format,
impl<F, A> Ord for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
<F as SliceFormat>::Slice: Ord,
A: Atomicity,
F: SliceFormat,
<F as SliceFormat>::Slice: Ord,
fn cmp(&self, other: &Tendril<F, A>) -> Ordering
fn max(self, other: Self) -> Self
1.21.0[src]
fn min(self, other: Self) -> Self
1.21.0[src]
fn clamp(self, min: Self, max: Self) -> Self
[src]
impl<F, A> PartialOrd<Tendril<F, A>> for Tendril<F, A> where
A: Atomicity,
F: SliceFormat,
<F as SliceFormat>::Slice: PartialOrd<<F as SliceFormat>::Slice>,
A: Atomicity,
F: SliceFormat,
<F as SliceFormat>::Slice: PartialOrd<<F as SliceFormat>::Slice>,
Auto Trait Implementations
impl<F, A = NonAtomic> !Sync for Tendril<F, A>
impl<F, A> Unpin for Tendril<F, A> where
A: Unpin,
A: Unpin,
impl<F, A> UnwindSafe for Tendril<F, A> where
A: UnwindSafe,
F: RefUnwindSafe,
A: UnwindSafe,
F: RefUnwindSafe,
impl<F, A = NonAtomic> !RefUnwindSafe for Tendril<F, A>
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,