Skip to main content

Encoder

Struct Encoder 

Source
pub struct Encoder<'b> { /* private fields */ }
Expand description

Serializes CBOR items into a fixed buffer.

On success each method advances the cursor by exactly the item’s preferred-encoding length. On failure (Error::OUT_OF_SPACE) nothing is written for that item, so the encoder stays valid and reusable.

Implementations§

Source§

impl<'b> Encoder<'b>

Source

pub const fn new(buf: &'b mut [u8]) -> Self

Creates an encoder writing into buf, starting at offset 0.

Examples found in repository?
examples/cbor-size.rs (line 94)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub const fn written(&self) -> usize

Number of bytes successfully written so far.

Examples found in repository?
examples/cbor-size.rs (line 102)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub const fn remaining(&self) -> usize

Number of bytes still available for writing.

Source

pub const fn finish(self) -> (&'b [u8], usize)

Consumes the encoder, returning the buffer and the bytes written.

Source

pub fn uint(&mut self, v: u64) -> Result<&mut Self, Error>

Encodes any unsigned integer using its preferred width.

Prefer the typed helpers (u8, u16, …); they compile to identical code and document the value’s range.

Examples found in repository?
examples/cbor-size.rs (line 98)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn nint(&mut self, n: u64) -> Result<&mut Self, Error>

Encodes -1 - n for magnitude n (RFC 8949 §3.1).

Magnitudes above i64::MIN’s range remain representable in CBOR, so this accepts the full u64 range.

Source

pub fn i64(&mut self, v: i64) -> Result<&mut Self, Error>

Encodes a signed integer.

Examples found in repository?
examples/cbor-size.rs (line 99)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn u8(&mut self, v: u8) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn u16(&mut self, v: u16) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn u32(&mut self, v: u32) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn u64(&mut self, v: u64) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn i8(&mut self, v: i8) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn i16(&mut self, v: i16) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn i32(&mut self, v: i32) -> Result<&mut Self, Error>

Encodes v.

Source

pub fn bytes(&mut self, b: &[u8]) -> Result<&mut Self, Error>

Encodes a byte string header followed by its contents.

Source

pub fn str(&mut self, s: &str) -> Result<&mut Self, Error>

Encodes a text string header followed by its UTF-8 contents.

Examples found in repository?
examples/cbor-size.rs (line 100)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn bool(&mut self, v: bool) -> Result<&mut Self, Error>

Encodes true or false.

Examples found in repository?
examples/cbor-size.rs (line 101)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn null(&mut self) -> Result<&mut Self, Error>

Encodes null.

Examples found in repository?
examples/cbor-size.rs (line 101)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn undefined(&mut self) -> Result<&mut Self, Error>

Encodes undefined. RFC 8949 §5.7 discourages its use on the wire, but the encoding is supported.

Source

pub fn simple(&mut self, s: Simple) -> Result<&mut Self, Error>

Encodes a simple value.

§Errors

Returns Error::INVALID_SIMPLE when the value would require the two-byte form while being below 32; RFC 8949 §3.3 forbids that form.

Source

pub fn tag(&mut self, number: u64) -> Result<&mut Self, Error>

Emits a tag header; encode the tagged item immediately after.

Tag semantics live outside this crate (RFC 8949 §3.4): only the tag number travels on the wire.

Source

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

Emits an array header for len following items.

Examples found in repository?
examples/cbor-size.rs (line 101)
90fn run_once() -> usize {
91    let mut buf = [0u8; 512];
92
93    // ---- always available: definite-length core --------------------
94    let mut e = Encoder::new(&mut buf);
95    let input: u64 = black_box(0xa1_2b_3c_4d_5e_6f_70_81);
96    let neg: i64 = black_box(-25_000);
97    let text: &str = black_box("heartbeat");
98    ok!(e.uint(input));
99    ok!(e.i64(neg));
100    ok!(e.str(text));
101    ok!(ok!(e.array_len(2)).null().and_then(|e| e.bool(true)));
102    let n = e.written();
103
104    let mut d = Decoder::new(black_box(&buf[..n]));
105    let _ = black_box(ok!(d.u64()));
106    let _ = black_box(ok!(d.i64()));
107    let _ = black_box(ok!(d.str()));
108    ok!(d.skip());
109
110    #[cfg(feature = "float")]
111    float_tier(&mut buf);
112
113    #[cfg(feature = "indefinite")]
114    indefinite_tier(&mut buf);
115
116    #[cfg(feature = "bignum")]
117    bignum_tier(&mut buf);
118
119    #[cfg(feature = "diagnostic")]
120    diagnostic_tier();
121
122    #[cfg(feature = "canonical")]
123    canonical_tier(&mut buf);
124
125    #[cfg(all(feature = "raw", feature = "indefinite"))]
126    raw_tier(&mut buf);
127
128    n
129}
Source

pub fn map_len(&mut self, pairs: usize) -> Result<&mut Self, Error>

Emits a map header for pairs following key/value pairs.

Trait Implementations§

Source§

impl<'b> Debug for Encoder<'b>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'b> !UnwindSafe for Encoder<'b>

§

impl<'b> Freeze for Encoder<'b>

§

impl<'b> RefUnwindSafe for Encoder<'b>

§

impl<'b> Send for Encoder<'b>

§

impl<'b> Sync for Encoder<'b>

§

impl<'b> Unpin for Encoder<'b>

§

impl<'b> UnsafeUnpin for Encoder<'b>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.