Struct bcder::Captured

pub struct Captured { /* fields omitted */ }

A wrapper for BER encoded data.

This types keeps a sequence of BER-encoded data in a Bytes value. It allows for delayed processing of this data and therefore zero-allocation handling of sequences and similar types by implementing iterators and helper types that work directly on the the still-encoded data.

You usually acquire a value of this type trough the capture family of methods on constructed BER content. Alternatively, you can also construct a new value using regular encoding via the from_values function or incrementally by starting with empty and then adding more content with [extent].

Once you have a captured value, you can use the decode method to decode the entire captured value or decode_partial to decode some values at the start of the captured value. The latter manipulates the captured content by moving past the captured values and is therefore perfect for an iterator.

The value also remembers what Mode the original data was decoded in and will automatically use this encoding in those methods.

Methods

impl Captured

pub fn from_values<V: Values>(mode: Mode, values: V) -> Self

Creates a captured value by encoding data.

The function takes a value encoder, encodes it into a bytes value with the given mode, and returns the resulting data as a captured value.

pub fn empty(mode: Mode) -> Self

Creates a new empty captured value in the given mode.

pub fn extend<V: Values>(&mut self, values: V)

Extends the captured value by encoding the given values.

The function encodes the given values in the captured value’s own mode and places the encoded content at the end of the captured value.

pub fn decode<F, T>(self, op: F) -> Result<T, Error> where
    F: FnOnce(&mut Constructed<Bytes>) -> Result<T, Error>, 

Decodes the full content using the provided function argument.

The method consumes the value. If you want to keep it around, simply clone it first. Since bytes values are cheap to clone, this is relatively cheap.

pub fn decode_partial<F, T>(&mut self, op: F) -> Result<T, Error> where
    F: FnOnce(&mut Constructed<&mut Bytes>) -> Result<T, Error>, 

Decodes the beginning of the content of the captured value.

The method calls op to parse a number of values from the beginning of the value and then advances the content of the captured value until after the end of these decoded values.

pub fn into_bytes(self) -> Bytes

Trades the value for a bytes value with the raw data.

pub fn as_slice(&self) -> &[u8]

Returns a bytes slice with the raw data of the captured value.

Methods from Deref<Target = Bytes>

pub fn len(&self) -> usize

Returns the number of bytes contained in this Bytes.

Examples

use bytes::Bytes;

let b = Bytes::from(&b"hello"[..]);
assert_eq!(b.len(), 5);

pub fn is_empty(&self) -> bool

Returns true if the Bytes has a length of 0.

Examples

use bytes::Bytes;

let b = Bytes::new();
assert!(b.is_empty());

pub fn slice(&self, begin: usize, end: usize) -> Bytes

Returns a slice of self for the index range [begin..end).

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 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.

pub fn slice_from(&self, begin: usize) -> Bytes

Returns a slice of self for the index range [begin..self.len()).

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) and is equivalent to self.slice(begin, self.len()).

Examples

use bytes::Bytes;

let a = Bytes::from(&b"hello world"[..]);
let b = a.slice_from(6);

assert_eq!(&b[..], b"world");

Panics

Requires that begin <= self.len(), otherwise slicing will panic.

pub fn slice_to(&self, end: usize) -> Bytes

Returns a slice of self for the index range [0..end).

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) and is equivalent to self.slice(0, end).

Examples

use bytes::Bytes;

let a = Bytes::from(&b"hello world"[..]);
let b = a.slice_to(5);

assert_eq!(&b[..], b"hello");

Panics

Requires that end <= self.len(), otherwise slicing will panic.

pub fn slice_ref(&self, subset: &[u8]) -> Bytes

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 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.

Trait Implementations

impl Values for Captured

fn encoded_len(&self, mode: Mode) -> usize

Returns the length of the encoded values for the given mode.

fn write_encoded<W: Write>(
    &self,
    mode: Mode,
    target: &mut W
) -> Result<(), Error>

Encodes the values in the given mode and writes them to target.

fn explicit(self, tag: Tag) -> Constructed<Self> where
    Self: Sized, 

Converts the encoder into one with an explicit tag.

fn to_captured(&self, mode: Mode) -> Captured

Captures the encoded values in the given mode.

impl Clone for Captured

fn clone(&self) -> Captured

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl AsRef<Bytes> for Captured

fn as_ref(&self) -> &Bytes

Performs the conversion.

impl AsRef<[u8]> for Captured

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl Deref for Captured

type Target = Bytes

The resulting type after dereferencing.

fn deref(&self) -> &Bytes

Dereferences the value.

impl Debug for Captured

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.