Struct bcder::decode::Primitive

pub struct Primitive<'a, S: 'a> { /* private fields */ }

The content octets of a primitive value.

You will receive a reference to a value of this type through a closure, possibly wrapped in a Content value. Your task will be to read out all the octets of the value before returning from the closure or produce an error if the value isn’t correctly encoded. If you read less octets than are available, whoever called the closure will produce an error after you returned. Thus, you can read as many octets as you expect and not bother to check whether that was all available octets.

The most basic way to do this is through the primitive’s implementation of the Source trait. Thus, you can gain access to some or all of the octets and mark them read by advancing over them. You can safely attempt to read more octets than available as that will reliably result in a malformed error.

A number of methods are available to deal with the encodings defined for various types. These are prefixed by to_ to indicate that they are intended to convert the content to a certain type. They all read exactly one encoded value.

The value provides access to the decoding mode via the mode method. All methodes that decode data will honour the decoding mode and enforce that data is encoded according to the mode.

Implementations

impl<'a, S: 'a> Primitive<'a, S>

Value Management

pub fn mode(&self) -> Mode

Returns the current decoding mode.

The higher-level to_ methods will use this mode to enforce that data is encoded correctly.

pub fn set_mode(&mut self, mode: Mode)

Sets the current decoding mode.

impl<'a, S: Source + 'a> Primitive<'a, S>

pub fn content_err(&self, err: impl Into<ContentError>) -> DecodeError<S::Error>

Produces a content error at the current source position.

impl<'a, S: Source + 'a> Primitive<'a, S>

High-level Decoding

pub fn to_bool(&mut self) -> Result<bool, DecodeError<S::Error>>

Parses the primitive value as a BOOLEAN value.

pub fn to_i8(&mut self) -> Result<i8, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a i8.

pub fn to_i16(&mut self) -> Result<i16, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a i8.

pub fn to_i32(&mut self) -> Result<i32, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a i8.

pub fn to_i64(&mut self) -> Result<i64, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a i8.

pub fn to_i128(&mut self) -> Result<i128, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a i8.

pub fn to_u8(&mut self) -> Result<u8, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a u8.

pub fn to_u16(&mut self) -> Result<u16, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a u16.

pub fn to_u32(&mut self) -> Result<u32, DecodeError<S::Error>>

Parses the primitive value as an INTEGER limited to a u32.

pub fn to_u64(&mut self) -> Result<u64, DecodeError<S::Error>>

Parses the primitive value as a INTEGER value limited to a u64.

pub fn to_u128(&mut self) -> Result<u64, DecodeError<S::Error>>

Parses the primitive value as a INTEGER value limited to a u128.

pub fn to_null(&mut self) -> Result<(), DecodeError<S::Error>>

Converts the content octets to a NULL value.

Since such a value is empty, this doesn’t really do anything.

impl<'a, S: Source + 'a> Primitive<'a, S>

Low-level Access

For basic low-level access, Primitive implements the Source trait. Because the length of the content is guaranteed to be known, it can provide a few additional methods. Note that these may still fail because the underlying source doesn’t guarantee that as many octets are actually available.

pub fn remaining(&self) -> usize

Returns the number of remaining octets.

The returned value reflects what is left of the expected length of content and therefore decreases when the primitive is advanced.

pub fn skip_all(&mut self) -> Result<(), DecodeError<S::Error>>

Skips the rest of the content.

Returns a malformed error if the source ends before the expected length of content.

pub fn take_all(&mut self) -> Result<Bytes, DecodeError<S::Error>>

Returns the remainder of the content as a Bytes value.

pub fn slice_all(&mut self) -> Result<&[u8], DecodeError<S::Error>>

Returns a bytes slice of the remainder of the content.

impl Primitive<'static, ()>

Support for Testing

pub fn decode_slice<F, T>(
    data: &[u8],
    mode: Mode,
    op: F
) -> Result<T, DecodeError<Infallible>> where
    F: FnOnce(&mut Primitive<'_, SliceSource<'_>>) -> Result<T, DecodeError<Infallible>>, 

Decode a bytes slice via a closure.

This method can be used in testing code for decoding primitive values by providing a bytes slice with the content. For instance, decoding the to_bool method could be tested like this:

use bcder::Mode;
use bcder::decode::Primitive;

assert_eq!(
    Primitive::decode_slice(
        b"\x00".as_ref(), Mode::Der,
        |prim| prim.to_bool()
    ).unwrap(),
    false
)

Trait Implementations

impl<'a, S: Source + 'a> Source for Primitive<'a, S>

type Error = <S as Source>::Error

The error produced when the source failed to read more data.

fn pos(&self) -> Pos

Returns the current logical postion within the sequence of data.

fn request(&mut self, len: usize) -> Result<usize, Self::Error>

Request at least len bytes to be available.

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

Returns a bytes slice with the available data.

fn bytes(&self, start: usize, end: usize) -> Bytes

Produces a Bytes value from part of the data.

fn advance(&mut self, len: usize)

Advance the source by len bytes.

fn skip(&mut self, len: usize) -> Result<usize, Self::Error>

Skip over the next len bytes.

fn take_u8(&mut self) -> Result<u8, DecodeError<Self::Error>>

Takes a single octet from the source.

fn take_opt_u8(&mut self) -> Result<Option<u8>, Self::Error>

Takes an optional octet from the source.

fn content_err(&self, err: impl Into<ContentError>) -> DecodeError<Self::Error>

Returns a content error at the current position of the source.