Struct ntex_bytes::Bytes [−][src]
pub struct Bytes { /* fields omitted */ }
Expand description
A reference counted contiguous slice of memory.
Bytes
is an efficient container for storing and operating on contiguous
slices of memory. It is intended for use primarily in networking code, but
could have applications elsewhere as well.
Bytes
values facilitate zero-copy network programming by allowing multiple
Bytes
objects to point to the same underlying memory. This is managed by
using a reference count to track when the memory is no longer needed and can
be freed.
use ntex_bytes::Bytes; let mut mem = Bytes::from(&b"Hello world"[..]); let a = mem.slice(0..5); assert_eq!(&a[..], b"Hello"); let b = mem.split_to(6); assert_eq!(&mem[..], b"world"); assert_eq!(&b[..], b"Hello ");
Memory layout
The Bytes
struct itself is fairly small, limited to a pointer to the
memory and 4 usize
fields used to track information about which segment of
the underlying memory the Bytes
handle has access to.
The memory layout looks like this:
+-------+
| Bytes |
+-------+
/ \_____
| \
v v
+-----+------------------------------------+
| Arc | | Data | |
+-----+------------------------------------+
Bytes
keeps both a pointer to the shared Arc
containing the full memory
slice and a pointer to the start of the region visible by the handle.
Bytes
also tracks the length of its view into the memory.
Sharing
The memory itself is reference counted, and multiple Bytes
objects may
point to the same region. Each Bytes
handle point to different sections within
the memory region, and Bytes
handle may or may not have overlapping views
into the memory.
Arc ptrs +---------+
________________________ / | Bytes 2 |
/ +---------+
/ +-----------+ | |
|_________/ | Bytes 1 | | |
| +-----------+ | |
| | | ___/ data | tail
| data | tail |/ |
v v v v
+-----+---------------------------------+-----+
| Arc | | | | |
+-----+---------------------------------+-----+
Mutating
While Bytes
handles may potentially represent overlapping views of the
underlying memory slice and may not be mutated, BytesMut
handles are
guaranteed to be the only handle able to view that slice of memory. As such,
BytesMut
handles are able to mutate the underlying memory. Note that
holding a unique view to a region of memory does not mean that there are no
other Bytes
and BytesMut
handles with disjoint views of the underlying
memory.
Inline bytes
As an optimization, when the slice referenced by a Bytes
or BytesMut
handle is small enough 1, with_capacity
will avoid the allocation
by inlining the slice directly in the handle. In this case, a clone is no
longer “shallow” and the data will be copied. Converting from a Vec
will
never use inlining.
Small enough: 31 bytes on 64 bit systems, 15 on 32 bit systems. ↩
Implementations
Creates a new Bytes
with the specified capacity.
The returned Bytes
will be able to hold at least capacity
bytes
without reallocating. If capacity
is under 4 * size_of::<usize>() - 1
,
then BytesMut
will not allocate.
It is important to note that this function does not specify the length
of the returned Bytes
, but only the capacity.
Examples
use ntex_bytes::Bytes; let mut bytes = Bytes::with_capacity(64); // `bytes` contains no data, even though there is capacity assert_eq!(bytes.len(), 0); bytes.extend_from_slice(&b"hello world"[..]); assert_eq!(&bytes[..], b"hello world");
Creates a new empty Bytes
.
This will not allocate and the returned Bytes
handle will be empty.
Examples
use ntex_bytes::Bytes; let b = Bytes::new(); assert_eq!(&b[..], b"");
Creates a new Bytes
from a static slice.
The returned Bytes
will point directly to the static slice. There is
no allocating or copying.
Examples
use ntex_bytes::Bytes; let b = Bytes::from_static(b"hello"); assert_eq!(&b[..], b"hello");
Returns the number of bytes contained in this Bytes
.
Examples
use ntex_bytes::Bytes; let b = Bytes::from(&b"hello"[..]); assert_eq!(b.len(), 5);
Returns true if the Bytes
has a length of 0.
Examples
use ntex_bytes::Bytes; let b = Bytes::new(); assert!(b.is_empty());
Return true if the Bytes
uses inline allocation
Examples
use ntex_bytes::Bytes; assert!(Bytes::with_capacity(4).is_inline()); assert!(!Bytes::from(Vec::with_capacity(4)).is_inline()); assert!(!Bytes::with_capacity(1024).is_inline());
Creates Bytes
instance from slice, by copying it.
Returns a slice of self for the provided range.
This will increment the reference count for the underlying memory and
return a new Bytes
handle set to the slice.
This operation is O(1)
.
Examples
use ntex_bytes::Bytes; let a = Bytes::from(&b"hello world"[..]); let b = a.slice(2..5); assert_eq!(&b[..], b"llo");
Panics
Requires that begin <= end
and end <= self.len()
, otherwise slicing
will panic.
Returns a slice of self that is equivalent to the given subset
.
When processing a Bytes
buffer with other tools, one often gets a
&[u8]
which is in fact a slice of the Bytes
, i.e. a subset of it.
This function turns that &[u8]
into another Bytes
, as if one had
called self.slice()
with the offsets that correspond to subset
.
This operation is O(1)
.
Examples
use ntex_bytes::Bytes; let bytes = Bytes::from(&b"012345678"[..]); let as_slice = bytes.as_ref(); let subset = &as_slice[2..6]; let subslice = bytes.slice_ref(&subset); assert_eq!(&subslice[..], b"2345");
Panics
Requires that the given sub
slice is in fact contained within the
Bytes
buffer; otherwise this function will panic.
Splits the bytes into two at the given index.
Afterwards self
contains elements [0, at)
, and the returned Bytes
contains elements [at, len)
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use ntex_bytes::Bytes; let mut a = Bytes::from(&b"hello world"[..]); let b = a.split_off(5); assert_eq!(&a[..], b"hello"); assert_eq!(&b[..], b" world");
Panics
Panics if at > len
.
Splits the bytes into two at the given index.
Afterwards self
contains elements [at, len)
, and the returned
Bytes
contains elements [0, at)
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use ntex_bytes::Bytes; let mut a = Bytes::from(&b"hello world"[..]); let b = a.split_to(5); assert_eq!(&a[..], b" world"); assert_eq!(&b[..], b"hello");
Panics
Panics if at > len
.
Shortens the buffer, keeping the first len
bytes and dropping the
rest.
If len
is greater than the buffer’s current length, this has no
effect.
The split_off
method can emulate truncate
, but this causes the
excess bytes to be returned instead of dropped.
Examples
use ntex_bytes::Bytes; let mut buf = Bytes::from(&b"hello world"[..]); buf.truncate(5); assert_eq!(buf, b"hello"[..]);
Shortens the buffer to len
bytes and dropping the rest.
This is useful if underlying buffer is larger than cuurrent bytes object.
Examples
use ntex_bytes::Bytes; let mut buf = Bytes::from(&b"hello world"[..]); buf.trimdown(); assert_eq!(buf, b"hello world"[..]);
Clears the buffer, removing all data.
Examples
use ntex_bytes::Bytes; let mut buf = Bytes::from(&b"hello world"[..]); buf.clear(); assert!(buf.is_empty());
Attempts to convert into a BytesMut
handle.
This will only succeed if there are no other outstanding references to
the underlying chunk of memory. Bytes
handles that contain inlined
bytes will always be convertible to BytesMut
.
Examples
use ntex_bytes::Bytes; let a = Bytes::copy_from_slice(&b"Mary had a little lamb, little lamb, little lamb..."[..]); // Create a shallow clone let b = a.clone(); // This will fail because `b` shares a reference with `a` let a = a.try_mut().unwrap_err(); drop(b); // This will succeed let mut a = a.try_mut().unwrap(); a[0] = b'b'; assert_eq!(&a[..4], b"bary");
Acquires a mutable reference to the owned form of the data.
Clones the data if it is not already owned.
Appends given bytes to this object.
If this Bytes
object has not enough capacity, it is resized first.
If it is shared (refcount > 1
), it is copied first.
This operation can be less effective than the similar operation on
BytesMut
, especially on small additions.
Examples
use ntex_bytes::Bytes; let mut buf = Bytes::from("aabb"); buf.extend_from_slice(b"ccdd"); buf.extend_from_slice(b"eeff"); assert_eq!(b"aabbccddeeff", &buf[..]);
Combine splitted Bytes objects back as contiguous.
If Bytes
objects were not contiguous originally, they will be extended.
Examples
use ntex_bytes::Bytes; let mut buf = Bytes::with_capacity(64); buf.extend_from_slice(b"aaabbbcccddd"); let splitted = buf.split_off(6); assert_eq!(b"aaabbb", &buf[..]); assert_eq!(b"cccddd", &splitted[..]); buf.unsplit(splitted); assert_eq!(b"aaabbbcccddd", &buf[..]);
Returns an iterator over the bytes contained by the buffer.
Examples
use ntex_bytes::{Buf, Bytes}; let buf = Bytes::from(&b"abc"[..]); let mut iter = buf.iter(); assert_eq!(iter.next().map(|b| *b), Some(b'a')); assert_eq!(iter.next().map(|b| *b), Some(b'b')); assert_eq!(iter.next().map(|b| *b), Some(b'c')); assert_eq!(iter.next(), None);
Trait Implementations
Returns the number of bytes between the current position and the end of the buffer. Read more
Returns a slice starting at the current position and of length between 0
and Buf::remaining()
. Note that this can return shorter slice (this allows
non-continuous internal representation). Read more
Returns true if there are any more bytes to consume Read more
Gets an unsigned 16 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 16 bit integer from self
in little-endian byte order. Read more
Gets a signed 16 bit integer from self
in big-endian byte order. Read more
Gets a signed 16 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 32 bit integer from self
in the big-endian byte order. Read more
Gets an unsigned 32 bit integer from self
in the little-endian byte order. Read more
Gets a signed 32 bit integer from self
in big-endian byte order. Read more
Gets a signed 32 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 64 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 64 bit integer from self
in little-endian byte order. Read more
Gets a signed 64 bit integer from self
in big-endian byte order. Read more
Gets a signed 64 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 128 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 128 bit integer from self
in little-endian byte order. Read more
Gets a signed 128 bit integer from self
in big-endian byte order. Read more
Gets a signed 128 bit integer from self
in little-endian byte order. Read more
Gets an unsigned n-byte integer from self
in big-endian byte order. Read more
Gets an unsigned n-byte integer from self
in little-endian byte order. Read more
Gets a signed n-byte integer from self
in big-endian byte order. Read more
Gets a signed n-byte integer from self
in little-endian byte order. Read more
Gets an IEEE754 single-precision (4 bytes) floating point number from
self
in big-endian byte order. Read more
Gets an IEEE754 single-precision (4 bytes) floating point number from
self
in little-endian byte order. Read more
Gets an IEEE754 double-precision (8 bytes) floating point number from
self
in big-endian byte order. Read more
Gets an IEEE754 double-precision (8 bytes) floating point number from
self
in little-endian byte order. Read more
Returns the number of bytes between the current position and the end of the buffer. Read more
Returns a slice starting at the current position and of length between 0
and Buf::remaining()
. Note that this can return shorter slice (this allows
non-continuous internal representation). Read more
Fills dst
with potentially multiple slices starting at self
’s
current position. Read more
Returns true if there are any more bytes to consume Read more
Gets an unsigned 16 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 16 bit integer from self
in little-endian byte order. Read more
Gets a signed 16 bit integer from self
in big-endian byte order. Read more
Gets a signed 16 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 32 bit integer from self
in the big-endian byte order. Read more
Gets an unsigned 32 bit integer from self
in the little-endian byte order. Read more
Gets a signed 32 bit integer from self
in big-endian byte order. Read more
Gets a signed 32 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 64 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 64 bit integer from self
in little-endian byte order. Read more
Gets a signed 64 bit integer from self
in big-endian byte order. Read more
Gets a signed 64 bit integer from self
in little-endian byte order. Read more
Gets an unsigned 128 bit integer from self
in big-endian byte order. Read more
Gets an unsigned 128 bit integer from self
in little-endian byte order. Read more
Gets a signed 128 bit integer from self
in big-endian byte order. Read more
Gets a signed 128 bit integer from self
in little-endian byte order. Read more
Gets an unsigned n-byte integer from self
in big-endian byte order. Read more
Gets an unsigned n-byte integer from self
in little-endian byte order. Read more
Gets a signed n-byte integer from self
in big-endian byte order. Read more
Gets a signed n-byte integer from self
in little-endian byte order. Read more
Gets an IEEE754 single-precision (4 bytes) floating point number from
self
in big-endian byte order. Read more
Gets an IEEE754 single-precision (4 bytes) floating point number from
self
in little-endian byte order. Read more
Gets an IEEE754 double-precision (8 bytes) floating point number from
self
in big-endian byte order. Read more
Gets an IEEE754 double-precision (8 bytes) floating point number from
self
in little-endian byte order. Read more
Consumes len
bytes inside self and returns new instance of Bytes
with this data. Read more
Creates an adaptor which will read at most limit
bytes from self
. Read more
Creates an adaptor which will chain this buffer with another. Read more
Extends a collection with the contents of an iterator. Read more
extend_one
)Extends a collection with exactly one element.
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
extend_one
)Extends a collection with exactly one element.
extend_one
)Reserves capacity in a collection for the given number of additional elements. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
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 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 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 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 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 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 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 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 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 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 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 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
Auto Trait Implementations
impl RefUnwindSafe for Bytes
impl UnwindSafe for Bytes
Blanket Implementations
Mutably borrows from an owned value. Read more