Struct cbor_data::CborBuilder

pub struct CborBuilder<'a, O: CborOutput> { /* private fields */ }

Builder for a single CBOR value.

CborOwned::canonical uses the default configuration, which implies writing bytes into a fresh Vec<u8> and finally moving them into a SmallVec. You can minimise allocations by reusing the build buffer, and you can influence whether definite or indefinite length encoding is used for arrays and dictionaries.

Example

use cbor_data::{Cbor, CborBuilder, Writer};

// this could come from a thread-local in real code:
let mut build_buffer = Vec::new();
// buffer will be cleared before use
build_buffer.extend_from_slice(b"some garbage");

let bytes_from_elsewhere = [0x82, 1, 2];
assert_eq!(Cbor::checked(&bytes_from_elsewhere).unwrap().to_string(), "[1, 2]");

let cbor = CborBuilder::with_scratch_space(&mut build_buffer)
    .with_max_definite_size(Some(1))
    .write_canonical(bytes_from_elsewhere.as_ref())
    .unwrap();

// now it is using indefinite-length encoding, since the array has more than 1 item
assert_eq!(cbor.to_string(), "[_ 1, 2]");
assert_eq!(cbor.as_slice(), [0x9f, 1, 2, 0xff]);

Implementations

impl<'a> CborBuilder<'a, WithOutput>

pub fn new() -> Self

Create a builder that writes into its own fresh vector.

pub fn with_scratch_space(v: &'a mut Vec<u8>) -> Self

Create a builder that clears the given vector and writes into it.

You can use this to reuse a scratch space across multiple values being built, e.g. by keeping the same vector in a thread-local variable.

impl<'a> CborBuilder<'a, NoOutput>

pub fn append_to(v: &'a mut Vec<u8>) -> Self

Append the CBOR bytes to the given vector and do not return a separate output value.

let mut v = Vec::new();
let result: () = CborBuilder::append_to(&mut v).write_pos(12, None);

assert_eq!(v, vec![12u8])

impl<'a, O: CborOutput> CborBuilder<'a, O>

pub fn with_max_definite_size(self, max_definite: Option<u64>) -> Self

Configure the limit above which indefinite size encoding will be used.

The default is 255, which is the largest size up to which definite size is at least as compact as indefinite size. Set to 23 to avoid moving bytes around when finishing the array. Set to None to always use indefinite size encoding.

Trait Implementations

impl Default for CborBuilder<'static, WithOutput>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, O: CborOutput> Writer for CborBuilder<'a, O>

type Output = <O as CborOutput>::Output

fn max_definite(&self) -> Option<u64>

Configured maximum array or dict length up to which definite size encoding is used.

fn write_pos(
    self,
    value: u64,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write a unsigned value of up to 64 bits. Tags are from outer to inner.

fn write_neg(
    self,
    value: u64,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write a negative value of up to 64 bits — the represented number is -1 - value. Tags are from outer to inner.

fn write_bytes(
    self,
    value: &[u8],
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write the given slice as a definite size byte string. Tags are from outer to inner.

fn write_bytes_chunked(
    self,
    value: impl IntoIterator<Item = impl AsRef<[u8]>> + Copy,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write the given slices as a definite size byte string. Tags are from outer to inner.

fn write_str(
    self,
    value: &str,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write the given slice as a definite size string. Tags are from outer to inner.

fn write_str_chunked(
    self,
    value: impl IntoIterator<Item = impl AsRef<str>> + Copy,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write the given slice as a definite size string. Tags are from outer to inner.

fn write_bool(
    self,
    value: bool,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Tags are from outer to inner.

fn write_null(self, tags: impl IntoIterator<Item = u64>) -> Self::Output

Tags are from outer to inner.

fn write_undefined(self, tags: impl IntoIterator<Item = u64>) -> Self::Output

Tags are from outer to inner.

fn write_lit(
    self,
    value: Literal,
    tags: impl IntoIterator<Item = u64>
) -> Self::Output

Write custom literal value — RFC 8949 §3.3 is required reading. Tags are from outer to inner.

fn write_array<F>(self, tags: impl IntoIterator<Item = u64>, f: F) -> Self::Outputwhere
    F: FnOnce(&mut ArrayWriter<'_>),

Write a nested array using the given closure that receives an array builder. Tags are from outer to inner.

fn write_array_ret<T, F>(
    self,
    tags: impl IntoIterator<Item = u64>,
    f: F
) -> (Self::Output, T)where
    F: FnOnce(&mut ArrayWriter<'_>) -> T,

Write a nested array using the given closure that receives an array builder. Tags are from outer to inner.

fn write_dict<F>(self, tags: impl IntoIterator<Item = u64>, f: F) -> Self::Outputwhere
    F: FnOnce(&mut DictWriter<'_>),

Write a nested dict using the given closure that receives a dict builder. Tags are from outer to inner.

fn write_dict_ret<T, F>(
    self,
    tags: impl IntoIterator<Item = u64>,
    f: F
) -> (Self::Output, T)where
    F: FnOnce(&mut DictWriter<'_>) -> T,

Write a nested dict using the given closure that receives a dict builder. Tags are from outer to inner.

fn write_canonical(self, bytes: &[u8]) -> Result<Self::Output, ParseError>

Interpret the given bytes as a single CBOR item and write it to this builder, canonicalising its contents like CborOwned::canonical()

fn write_trusting(self, bytes: &[u8]) -> Self::Output

Assume that the given bytes are a well-formed single CBOR item and write it to this builder.

fn write_item(self, item: &Cbor) -> Self::Output

Write the given CBOR item