[−][src]Struct domain_core::bits::compose::Compressor
A buffer for composing a compressed DNS message.
This type wraps a BytesMut
value into which it composes a message,
growing it as necessary. It provides an implementation for BufMut
allowing it to be used like any other buffer. In addition, it provides
special handling for types that implement Compose
via the
compose
method, appending them if there’s
enough space.
The whole point of this type is, of course, name compression. This is
being provided via the compress_name
method which appends any domain
name. Since compression is actually rather expensive as we need to keep
track of names that have been written so far, it needs to be explicitely
enabled via the enable_compression
method.
Two more methods for tweaking the behaviour of Compressor
are available.
The maximum size of a message can be set via the set_limit
. A value
will grow its underlying buffer as needed up to at most this size. It
will re-allocate memory if necessary by the amount set through
set_page_size
. By default, or if the page size is set to 0, it will
only allocate exactly once to have enough space to reach the current
limit.
Once you are done composing your message, you can either extract the
underlying BytesMut
via unwrap
or get it as a frozen Bytes
directly via freeze
.
Note: Name compression is currently implemented in a rather naive way
by simply storing each compressed name’s position in a hash map
(also considering all its parents). This can probably be optimized.
In addition, this approach doesn’t
consider non-compressed names (since they are appended via their
Compose
implementation).
Methods
impl Compressor
[src]
pub fn from_buf(buf: BytesMut) -> Self
[src]
Creates a compressor from the given bytes buffer.
The compressor will have a default limit equal to the buffer’s current capacity and a page size of 0.
pub fn new() -> Self
[src]
Creates a new compressor with a default capacity and limit.
The compressor will be created atop a new buffer which will use its default capacity. This is the largest capacity it can use without having to allocate. The compressor will start out with a limit equal to this capacity and a page size of 0.
pub fn with_capacity(capacity: usize) -> Self
[src]
Creates a new compressor with the given capacity.
The compressor will be created atop a new buffer with at least the
given capacity. The compressor’s initial limit will be the actual
capacity of the buffer which may be larger than capacity
. The
initial page size will be 0.
pub fn enable_compression(&mut self)
[src]
Enable name compression.
By default, a compressor will not actually compress domain names, but rather append them like any other data. Instead, compression needs to be enable once via this method.
pub fn set_limit(&mut self, limit: usize)
[src]
Sets the size limit for the compressor.
This limit only regards the part of the underlying buffer that is
being built by the compressor. That is, if the compressor was created
on top of a buffer that already contained data, the buffer will never
exceed that amount of data plus limit
.
If you try to set the limit to a value smaller than what has already been added so far, the limit will silently be increased to that amount.
A new compressor starts out with a size limit equal to the remaining capacity of the buffer it is being created with.
pub fn set_page_size(&mut self, page_size: usize)
[src]
Sets the number of bytes by which the buffer should be grown.
Each time the buffer runs out of capacity and is still below its
size limit, it will be grown by page_size
bytes. This may result in
a buffer with more capacity than the limit.
If page_size
is set to 0, the buffer will be expanded only once to
match the size limit.
A new compressor starts out with this specia page size of 0.
pub fn unwrap(self) -> BytesMut
[src]
Trades in the compressor for its underlying bytes buffer.
pub fn freeze(self) -> Bytes
[src]
Trades in the compressor for the frozen underlying buffer.
pub fn so_far(&self) -> &[u8]
[src]
Returns a reference to the bytes that have been assembled so far.
This differs from as_slice
if the compressor
was created atop an existing buffer in that the slice does not
contain the data that was in the buffer before.
pub fn so_far_mut(&mut self) -> &mut [u8]
[src]
Returns a mutable reference to the data assembled so far.
This differs from as_slice_mut
if the
compressor was created atop an existing buffer in that the slice
does not contain the data that was in the buffer before.
pub fn compress_name<N: ToDname>(&mut self, name: &N) -> Result<(), ShortBuf>
[src]
Composes a the given name compressed into the buffer.
If compression hasn’t been enable yet via
enable_compression
, the name will be
appended without compression. It will also not be remembered as a
compression target for later names.
pub fn compose<C: ?Sized>(&mut self, what: &C) -> Result<(), ShortBuf> where
C: Compose,
[src]
C: Compose,
Appends something composable to the end of the buffer.
This method can be used to append something and short circuit via the
question mark operator if it doesn’t fit. This is most helpful when
implementing the Compress
trait for a
composite type.
pub fn as_slice(&self) -> &[u8]
[src]
Returns a reference to the complete data of the underlying buffer.
This may be more than the assembled data if the compressor was created atop a buffer that already contained data.
pub fn as_slice_mut(&mut self) -> &mut [u8]
[src]
Returns a mutable reference to the data of the underlying buffer.
This may be more than the assembled data if the compressor was created atop a buffer that already contained data.
Methods from Deref<Target = BytesMut>
pub fn len(&self) -> usize
[src]
Returns the number of bytes contained in this BytesMut
.
Examples
use bytes::BytesMut; let b = BytesMut::from(&b"hello"[..]); assert_eq!(b.len(), 5);
pub fn is_empty(&self) -> bool
[src]
Returns true if the BytesMut
has a length of 0.
Examples
use bytes::BytesMut; let b = BytesMut::with_capacity(64); assert!(b.is_empty());
pub fn capacity(&self) -> usize
[src]
Returns the number of bytes the BytesMut
can hold without reallocating.
Examples
use bytes::BytesMut; let b = BytesMut::with_capacity(64); assert_eq!(b.capacity(), 64);
pub fn split_off(&mut self, at: usize) -> BytesMut
[src]
Splits the bytes into two at the given index.
Afterwards self
contains elements [0, at)
, and the returned
BytesMut
contains elements [at, capacity)
.
This is an O(1)
operation that just increases the reference count
and sets a few indices.
Examples
use bytes::BytesMut; let mut a = BytesMut::from(&b"hello world"[..]); let mut b = a.split_off(5); a[0] = b'j'; b[0] = b'!'; assert_eq!(&a[..], b"jello"); assert_eq!(&b[..], b"!world");
Panics
Panics if at > capacity
.
pub fn take(&mut self) -> BytesMut
[src]
Removes the bytes from the current view, returning them in a new
BytesMut
handle.
Afterwards, self
will be empty, but will retain any additional
capacity that it had before the operation. This is identical to
self.split_to(self.len())
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use bytes::{BytesMut, BufMut}; let mut buf = BytesMut::with_capacity(1024); buf.put(&b"hello world"[..]); let other = buf.take(); assert!(buf.is_empty()); assert_eq!(1013, buf.capacity()); assert_eq!(other, b"hello world"[..]);
pub fn split_to(&mut self, at: usize) -> BytesMut
[src]
Splits the buffer into two at the given index.
Afterwards self
contains elements [at, len)
, and the returned BytesMut
contains elements [0, at)
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use bytes::BytesMut; let mut a = BytesMut::from(&b"hello world"[..]); let mut b = a.split_to(5); a[0] = b'!'; b[0] = b'j'; assert_eq!(&a[..], b"!world"); assert_eq!(&b[..], b"jello");
Panics
Panics if at > len
.
pub fn truncate(&mut self, len: usize)
[src]
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 bytes::BytesMut; let mut buf = BytesMut::from(&b"hello world"[..]); buf.truncate(5); assert_eq!(buf, b"hello"[..]);
pub fn advance(&mut self, cnt: usize)
[src]
Shortens the buffer, dropping the first cnt
bytes and keeping the
rest.
This is the same function as Buf::advance
, and in the next breaking
release of bytes
, this implementation will be removed in favor of
having BytesMut
implement Buf
.
Panics
This function panics if cnt
is greater than self.len()
pub fn clear(&mut self)
[src]
Clears the buffer, removing all data.
Examples
use bytes::BytesMut; let mut buf = BytesMut::from(&b"hello world"[..]); buf.clear(); assert!(buf.is_empty());
pub fn resize(&mut self, new_len: usize, value: u8)
[src]
Resizes the buffer so that len
is equal to new_len
.
If new_len
is greater than len
, the buffer is extended by the
difference with each additional byte set to value
. If new_len
is
less than len
, the buffer is simply truncated.
Examples
use bytes::BytesMut; let mut buf = BytesMut::new(); buf.resize(3, 0x1); assert_eq!(&buf[..], &[0x1, 0x1, 0x1]); buf.resize(2, 0x2); assert_eq!(&buf[..], &[0x1, 0x1]); buf.resize(4, 0x3); assert_eq!(&buf[..], &[0x1, 0x1, 0x3, 0x3]);
pub unsafe fn set_len(&mut self, len: usize)
[src]
Sets the length of the buffer.
This will explicitly set the size of the buffer without actually modifying the data, so it is up to the caller to ensure that the data has been initialized.
Examples
use bytes::BytesMut; let mut b = BytesMut::from(&b"hello world"[..]); unsafe { b.set_len(5); } assert_eq!(&b[..], b"hello"); unsafe { b.set_len(11); } assert_eq!(&b[..], b"hello world");
Panics
This method will panic if len
is out of bounds for the underlying
slice or if it comes after the end
of the configured window.
pub fn reserve(&mut self, additional: usize)
[src]
Reserves capacity for at least additional
more bytes to be inserted
into the given BytesMut
.
More than additional
bytes may be reserved in order to avoid frequent
reallocations. A call to reserve
may result in an allocation.
Before allocating new buffer space, the function will attempt to reclaim space in the existing buffer. If the current handle references a small view in the original buffer and all other handles have been dropped, and the requested capacity is less than or equal to the existing buffer's capacity, then the current view will be copied to the front of the buffer and the handle will take ownership of the full buffer.
Examples
In the following example, a new buffer is allocated.
use bytes::BytesMut; let mut buf = BytesMut::from(&b"hello"[..]); buf.reserve(64); assert!(buf.capacity() >= 69);
In the following example, the existing buffer is reclaimed.
use bytes::{BytesMut, BufMut}; let mut buf = BytesMut::with_capacity(128); buf.put(&[0; 64][..]); let ptr = buf.as_ptr(); let other = buf.take(); assert!(buf.is_empty()); assert_eq!(buf.capacity(), 64); drop(other); buf.reserve(128); assert_eq!(buf.capacity(), 128); assert_eq!(buf.as_ptr(), ptr);
Panics
Panics if the new capacity overflows usize
.
pub fn extend_from_slice(&mut self, extend: &[u8])
[src]
Appends given bytes to this object.
If this BytesMut
object has not enough capacity, it is resized first.
So unlike put_slice
operation, extend_from_slice
does not panic.
Examples
use bytes::BytesMut; let mut buf = BytesMut::with_capacity(0); buf.extend_from_slice(b"aaabbb"); buf.extend_from_slice(b"cccddd"); assert_eq!(b"aaabbbcccddd", &buf[..]);
pub fn unsplit(&mut self, other: BytesMut)
[src]
Combine splitted BytesMut objects back as contiguous.
If BytesMut
objects were not contiguous originally, they will be extended.
Examples
use bytes::BytesMut; let mut buf = BytesMut::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[..]);
Trait Implementations
impl Clone for Compressor
[src]
fn clone(&self) -> Compressor
[src]
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl AsMut<BytesMut> for Compressor
[src]
impl AsMut<[u8]> for Compressor
[src]
impl AsRef<BytesMut> for Compressor
[src]
impl AsRef<[u8]> for Compressor
[src]
impl Default for Compressor
[src]
impl DerefMut for Compressor
[src]
impl Deref for Compressor
[src]
impl Debug for Compressor
[src]
impl BufMut for Compressor
[src]
fn remaining_mut(&self) -> usize
[src]
unsafe fn advance_mut(&mut self, cnt: usize)
[src]
unsafe fn bytes_mut(&mut self) -> &mut [u8]
[src]
fn has_remaining_mut(&self) -> bool
[src]
Returns true if there is space in self
for more bytes. Read more
unsafe fn bytes_vec_mut(&'a mut self, dst: &mut [&'a mut IoVec]) -> usize
[src]
Fills dst
with potentially multiple mutable slices starting at self
's current position. Read more
fn put<T>(&mut self, src: T) where
T: IntoBuf,
[src]
T: IntoBuf,
Transfer bytes into self
from src
and advance the cursor by the number of bytes written. Read more
fn put_slice(&mut self, src: &[u8])
[src]
Transfer bytes into self
from src
and advance the cursor by the number of bytes written. Read more
fn put_u8(&mut self, n: u8)
[src]
Writes an unsigned 8 bit integer to self
. Read more
fn put_i8(&mut self, n: i8)
[src]
Writes a signed 8 bit integer to self
. Read more
fn put_u16_be(&mut self, n: u16)
[src]
Writes an unsigned 16 bit integer to self
in big-endian byte order. Read more
fn put_u16_le(&mut self, n: u16)
[src]
Writes an unsigned 16 bit integer to self
in little-endian byte order. Read more
fn put_i16_be(&mut self, n: i16)
[src]
Writes a signed 16 bit integer to self
in big-endian byte order. Read more
fn put_i16_le(&mut self, n: i16)
[src]
Writes a signed 16 bit integer to self
in little-endian byte order. Read more
fn put_u32_be(&mut self, n: u32)
[src]
Writes an unsigned 32 bit integer to self
in big-endian byte order. Read more
fn put_u32_le(&mut self, n: u32)
[src]
Writes an unsigned 32 bit integer to self
in little-endian byte order. Read more
fn put_i32_be(&mut self, n: i32)
[src]
Writes a signed 32 bit integer to self
in big-endian byte order. Read more
fn put_i32_le(&mut self, n: i32)
[src]
Writes a signed 32 bit integer to self
in little-endian byte order. Read more
fn put_u64_be(&mut self, n: u64)
[src]
Writes an unsigned 64 bit integer to self
in the big-endian byte order. Read more
fn put_u64_le(&mut self, n: u64)
[src]
Writes an unsigned 64 bit integer to self
in little-endian byte order. Read more
fn put_i64_be(&mut self, n: i64)
[src]
Writes a signed 64 bit integer to self
in the big-endian byte order. Read more
fn put_i64_le(&mut self, n: i64)
[src]
Writes a signed 64 bit integer to self
in little-endian byte order. Read more
fn put_uint_be(&mut self, n: u64, nbytes: usize)
[src]
Writes an unsigned n-byte integer to self
in big-endian byte order. Read more
fn put_uint_le(&mut self, n: u64, nbytes: usize)
[src]
Writes an unsigned n-byte integer to self
in the little-endian byte order. Read more
fn put_int_be(&mut self, n: i64, nbytes: usize)
[src]
Writes a signed n-byte integer to self
in big-endian byte order. Read more
fn put_int_le(&mut self, n: i64, nbytes: usize)
[src]
Writes a signed n-byte integer to self
in little-endian byte order. Read more
fn put_f32_be(&mut self, n: f32)
[src]
Writes an IEEE754 single-precision (4 bytes) floating point number to self
in big-endian byte order. Read more
fn put_f32_le(&mut self, n: f32)
[src]
Writes an IEEE754 single-precision (4 bytes) floating point number to self
in little-endian byte order. Read more
fn put_f64_be(&mut self, n: f64)
[src]
Writes an IEEE754 double-precision (8 bytes) floating point number to self
in big-endian byte order. Read more
fn put_f64_le(&mut self, n: f64)
[src]
Writes an IEEE754 double-precision (8 bytes) floating point number to self
in little-endian byte order. Read more
fn by_ref(&mut self) -> &mut Self
[src]
Creates a "by reference" adaptor for this instance of BufMut
. Read more
fn writer(self) -> Writer<Self>
[src]
Creates an adaptor which implements the Write
trait for self
. Read more
Auto Trait Implementations
impl Send for Compressor
impl Sync for Compressor
Blanket Implementations
impl<T, U> Into for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
impl<T> From for T
[src]
impl<T, U> TryFrom for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = !
try_from
)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> Borrow for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T, U> TryInto for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
try_from
)The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> BorrowMut for T where
T: ?Sized,
[src]
T: ?Sized,