Struct bcder::captured::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.

Implementations

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 builder(mode: Mode) -> CapturedBuilder

Crates a builder for a captured value in the given mode.

pub fn into_builder(self) -> CapturedBuilder

Converts the captured values into a builder in order to add new values.

Because the captured values might be shared, this requires copying the underlying data.

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, range: impl RangeBounds<usize>) -> Bytes

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 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_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 AsRef<[u8]> for Captured

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

Performs the conversion.

impl AsRef<Bytes> for Captured

pub fn as_ref(&self) -> &Bytes

Performs the conversion.

impl Clone for Captured

pub fn clone(&self) -> Captured

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Captured

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Captured

type Target = Bytes

The resulting type after dereferencing.

pub fn deref(&self) -> &Bytes

Dereferences the value.

impl From<Captured> for CapturedBuilder

pub fn from(src: Captured) -> Self

Performs the conversion.

impl Values for Captured

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

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

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

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

Converts the encoder into one with an explicit tag.

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

Captures the encoded values in the given mode.