ciborium

The ciborium-io crate provides low-level Read and Write traits designed for environments where std::io is unavailable, such as no_std or no_alloc contexts. These traits are simplified versions of the standard library counterparts and are designed to be zero-cost abstractions.

Supported Implementations

• Byte Slices: Always supported.
• std::io types: Supported if the std feature is enabled (via blanket implementations).
• Vec<u8>: Supported if the alloc feature is enabled.
• Custom Types: You can implement the Read and Write traits for your own types to integrate with the rest of the ciborium ecosystem.

To encode values, create an Encoder from a writer. Use Encoder::push() to write a Header to the wire. After writing the header, you can write the item body directly.

Utility functions:

• Encoder::bytes(): Properly segments byte output on the wire.
• Encoder::text(): Properly segments text output on the wire.
• Encoder::flush(): Finalizes the encoding process.

use ciborium_ll::{Encoder, Header};
use ciborium_io::Write as _;

let mut buffer = [0u8; 19];
let mut encoder = Encoder::from(&mut buffer[..]);

// Write the structure
encoder.push(Header::Map(Some(1))).unwrap();
encoder.push(Header::Positive(7)).unwrap();
encoder.text("Hello, World!", 7).unwrap();

// Validate our output
encoder.flush().unwrap();
assert_eq!(b"\xa1\x07\x7f\x67Hello, \x66World!\xff", &buffer[..]);

Unlike many other serde parsers that use BTreeMap or HashMap for map types, Ciborium represents the Map type using Vec<(Value, Value)>.

This design choice ensures that the order of key-value pairs is preserved exactly as they appear on the wire. If you require the properties of a BTreeMap or HashMap, you can convert the resulting vector using .collect().

Ciborium always serializes numeric values to the smallest possible lossless encoding.

For example, 1u128 is serialized as a single byte (01). During decoding, these small encodings are losslessly coerced back into the target type (e.g., a u128).

For floating-point numbers, coercion to a smaller size only occurs if the raw bits remain identical when coerced back to the original size. This approach ensures maximum compatibility with dynamic languages like Python that do not use fixed integer widths.

Ciborium follows the Robustness Principle: it aims to be liberal in what it accepts.

• Decoding: Ciborium aims to be wire-compatible with other implementations. For example, it can successfully decode encodings produced by serde_cbor, even though serde_cbor uses fixed-width encoding and does not perform lossless coercion.
• Encoding: Ciborium may not necessarily be wire-compatible with other implementations when encoding, due to its preference for smallest-size numeric serialization.

Ciborium provides CBOR (Concise Binary Object Representation) implementations for serde.

To deserialize CBOR data from a reader, use from_reader(). To serialize data into a writer, use into_writer().

Both functions accept any type that implements Read or Write, including byte slices (&[u8]) or streams. For working with dynamic CBOR values without a predefined schema, use the Value type.

// Note: The following is a conceptual usage pattern based on the documentation
// as exact imports depend on the crate structure.

// Deserialization
let data: MyStruct = ciborium::de::from_reader(reader).unwrap();

// Serialization
ciborium::ser::into_writer(my_instance, writer).unwrap();

// Dynamic values
let value: ciborium::value::Value = ciborium::de::from_reader(reader).unwrap();

CBOR supports segmented bytes and text. To handle these correctly, ciborium-ll provides bytes() and text() methods that return a Segments iterator.

To use them correctly:

1. Call decoder.pull() to get the header.
2. If the header is Header::Bytes(len) or Header::Text(len), call decoder.bytes(len) or decoder.text(len) respectively.
3. You must pass the len obtained from the header into these methods.

These methods encapsulate the logic for navigating segmented data, which can be complex to implement manually.

// Example for segmented bytes
if let Header::Bytes(len) = decoder.pull()? {
    let segments = decoder.bytes(Some(len));
    for segment in segments {
        // process segment
    }
}

The Value enum is a dynamic representation of CBOR data. It can hold various types including integers, bytes, floats, text, booleans, null, tags, arrays, and maps. You can create Value instances using the From trait for most standard Rust types.

use ciborium::Value;

let val = Value::Text("hello".to_string());
let arr = Value::Array(vec![Value::Bool(true), Value::Null]);
let map = Value::Map(vec![(Value::Text("key".into()), Value::Integer(17.into()))]);

The Value enum provides several methods to inspect and extract its underlying data. Methods generally follow these patterns:

• is_<type>(): Returns true if the value matches the type.
• as_<type>(): Returns an Option<&T> (immutable reference) or Option<&mut T> (mutable reference) if the type matches.
• into_<type>(): Consumes the Value and returns Result<T, Value>, returning the underlying data if successful or the original Value in an Err if the type mismatch occurs.