Enum Value

Source

pub enum Value {
    SimpleValue(SimpleValue),
    Unsigned(u64),
    Negative(u64),
    Float(Float),
    ByteString(Vec<u8>),
    TextString(String),
    Array(Vec<Value>),
    Map(BTreeMap<Value, Value>),
    Tag(u64, Box<Value>),
}

Expand description

A single CBOR data item.

Value covers all CBOR major types: integers, floats, byte and text strings, arrays, maps, tagged values, and simple values (null, booleans). It encodes deterministically and decodes only canonical input.

§Creating values

Rust primitives convert via From:

use cbor_core::Value;

let n = Value::from(42);
let s = Value::from("hello");
let b = Value::from(true);

The array! and map! macros build arrays and maps from literals:

use cbor_core::{Value, array, map};

let a = array![1, 2, 3];
let m = map! { "x" => 10, "y" => 20 };

Arrays and maps can also be built from standard Rust collections. Slices, Vecs, fixed-size arrays, BTreeMaps, HashMaps, and slices of key-value pairs all convert automatically:

use cbor_core::Value;
use std::collections::HashMap;

// Array from a slice
let a = Value::array([1, 2, 3].as_slice());

// Map from a HashMap
let mut hm = HashMap::new();
hm.insert(1, 2);
let m = Value::map(&hm);

// Map from key-value pairs
let m = Value::map([("x", 10), ("y", 20)]);

Use () to create empty arrays or maps without spelling out a type:

use cbor_core::Value;

let empty_array = Value::array(());
let empty_map = Value::map(());

assert_eq!(empty_array.len(), Some(0));
assert_eq!(empty_map.len(), Some(0));

Named constructors are available for cases where From is ambiguous or unavailable:

Constructor	Builds
`Value::new(v)`	Any variant via `TryFrom`, panicking on fallible failures
`Value::null()`	Null simple value
`Value::simple_value(v)`	Arbitrary simple value
`Value::float(v)`	Float in shortest CBOR form
`Value::byte_string(v)`	Byte string from `impl Into<Vec<u8>>`
`Value::text_string(v)`	Text string from `impl Into<String>`
`Value::array(v)`	Array from slice, `Vec`, or fixed-size array
`Value::map(v)`	Map from `BTreeMap`, `HashMap`, slice of pairs, etc.
`Value::date_time(v)`	Date/time string (tag 0)
`Value::epoch_time(v)`	Epoch time (tag 1)
`Value::tag(n, v)`	Tagged value

§`const` constructors

Scalar variants can also be built in const context. These are the const counterparts of the From<T> implementations. Use them for const items; in non-const code the shorter Value::from(v) or Value::new(v) spellings are preferred.

Constructor	Builds
`Value::null()`	Null simple value
`Value::simple_value(v)`	Simple value from `u8`
`Value::from_bool(v)`	Boolean
`Value::from_u64(v)`	Unsigned integer
`Value::from_i64(v)`	Signed integer
`Value::from_f32(v)`	Float from `f32`
`Value::from_f64(v)`	Float from `f64`
`Value::from_payload(v)`	Non-finite float from payload

Narrower integer widths (u8..u32, i8..i32) are not provided separately: as u64 / as i64 is lossless and yields the same Value. u128 and i128 have no const constructor because out-of-range values require the big-integer path, which allocates a tagged byte string. Byte strings, text strings, arrays, maps, and tags are heap-backed and likewise cannot be built in const context.

§Encoding and decoding

use cbor_core::Value;

let original = Value::from(-1000);
let bytes = original.encode();
let decoded = Value::decode(&bytes).unwrap();
assert_eq!(original, decoded);

CBOR can be produced and consumed as binary bytes, as a hex string, or as diagnostic notation text:

Direction	Binary	Hex string	Diagnostic text
Produce (owned)	`encode` → `Vec<u8>`	`encode_hex` → `String`	`format!("{v:?}")` (compact) or `format!("{v:#?}")` (pretty) via `Debug`; `format!("{v}")` via `Display`
Produce (streaming)	`write_to`(`impl Write`)	`write_hex_to`(`impl Write`)	—
Consume (owned)	`decode`(`impl AsRef<[u8]>`)	`decode_hex`(`impl AsRef<[u8]>`)	`str::parse` via `FromStr`
Consume (streaming)	`read_from`(`impl Read`)	`read_hex_from`(`impl Read`)	—

Debug output follows CBOR::Core diagnostic notation (Section 2.3.6); Display forwards to Debug so both produce the same text. format!("{v:?}").parse::<Value>() always round-trips.

The four decoding methods above forward to a default DecodeOptions. Use that type directly to switch between binary and hex at runtime, or to adjust the recursion limit, the declared-length cap, or the OOM-mitigation budget — for example, to tighten limits on input from an untrusted source:

use cbor_core::DecodeOptions;

let strict = DecodeOptions::new()
    .recursion_limit(16)
    .length_limit(4096)
    .oom_mitigation(64 * 1024);

let v = strict.decode([0x18, 42]).unwrap();
assert_eq!(v.to_u32().unwrap(), 42);

§Accessors

Accessor methods extract or borrow the inner data of each variant. All return Result<T>, yielding Err(Error::IncompatibleType) on a type mismatch. The naming follows Rust conventions:

Prefix	Meaning	Returns
`as_*`	Borrow inner data	`&T` or `&mut T` (with `_mut`)
`to_*`	Convert or narrow	Owned `Copy` type (`u8`, `f32`, …)
`into_*`	Consume self, extract	Owned `T`
no prefix	Trivial property	`Copy` scalar

§Simple values

In CBOR, booleans and null are not distinct types but specific simple values: false is 20, true is 21, null is 22. This means a boolean value is always also a simple value. to_bool provides typed access to true/false, while to_simple_value works on any simple value including booleans and null.

Method	Returns	Notes
`to_simple_value`	`Result<u8>`	Raw simple value number
`to_bool`	`Result<bool>`	Only for `true`/`false`

use cbor_core::Value;

let v = Value::from(true);
assert_eq!(v.to_bool().unwrap(), true);
assert_eq!(v.to_simple_value().unwrap(), 21); // CBOR true = simple(21)

// null is also a simple value
let n = Value::null();
assert!(n.to_bool().is_err());              // not a boolean
assert_eq!(n.to_simple_value().unwrap(), 22); // but is simple(22)

§Integers

CBOR has effectively four integer types (unsigned or negative, and normal or big integer) with different internal representations. This is handled transparently by the API.

The to_* accessors perform checked narrowing into any Rust integer type, returning Err(Overflow) if the value does not fit, or Err(NegativeUnsigned) when extracting a negative value into an unsigned type.

Method	Returns
`to_u8` .. `to_u128`, `to_usize`	`Result<uN>`
`to_i8` .. `to_i128`, `to_isize`	`Result<iN>`

use cbor_core::Value;

let v = Value::from(1000);
assert_eq!(v.to_u32().unwrap(), 1000);
assert_eq!(v.to_i64().unwrap(), 1000);
assert!(v.to_u8().is_err()); // overflow

let neg = Value::from(-5);
assert_eq!(neg.to_i8().unwrap(), -5);
assert!(neg.to_u32().is_err()); // negative unsigned

§Floats

Floats are stored internally in their shortest CBOR encoding (f16, f32, or f64). to_f64 always succeeds since every float can widen to f64. to_f32 fails with Err(Precision) if the value is stored as f64. A float internally stored as f16 can always be converted to either an f32 or f64 for obvious reasons.

Method	Returns
`to_f32`	`Result<f32>` (fails for f64 values)
`to_f64`	`Result<f64>`

use cbor_core::Value;

let v = Value::from(2.5);
assert_eq!(v.to_f64().unwrap(), 2.5);
assert_eq!(v.to_f32().unwrap(), 2.5);

§Byte strings

Byte strings are stored as Vec<u8>. Use as_bytes for a borrowed slice, or into_bytes to take ownership without copying.

Method	Returns
`as_bytes`	`Result<&[u8]>`
`as_bytes_mut`	`Result<&mut Vec<u8>>`
`into_bytes`	`Result<Vec<u8>>`

use cbor_core::Value;

let mut v = Value::from(vec![1, 2, 3]);
v.as_bytes_mut().unwrap().push(4);
assert_eq!(v.as_bytes().unwrap(), &[1, 2, 3, 4]);

§Text strings

Text strings are stored as String (guaranteed valid UTF-8 by the decoder). Use as_str for a borrowed &str, or into_string to take ownership.

Method	Returns
`as_str`	`Result<&str>`
`as_string_mut`	`Result<&mut String>`
`into_string`	`Result<String>`

use cbor_core::Value;

let v = Value::from("hello");
assert_eq!(v.as_str().unwrap(), "hello");

// Modify in place
let mut v = Value::from("hello");
v.as_string_mut().unwrap().push_str(" world");
assert_eq!(v.as_str().unwrap(), "hello world");

§Arrays

Arrays are stored as Vec<Value>. Use as_array to borrow the elements as a slice, or as_array_mut to modify them in place. For element access by index, see get, get_mut, remove, and the Index/IndexMut implementations — see the Indexing section below.

Method	Returns
`as_array`	`Result<&[Value]>`
`as_array_mut`	`Result<&mut Vec<Value>>`
`into_array`	`Result<Vec<Value>>`

use cbor_core::{Value, array};

let v = array![10, 20, 30];
let items = v.as_array().unwrap();
assert_eq!(items[1].to_u32().unwrap(), 20);

// Modify in place
let mut v = array![1, 2];
v.append(3);
assert_eq!(v.len(), Some(3));

§Maps

Maps are stored as BTreeMap<Value, Value>, giving canonical key order. Use as_map for direct access to the underlying BTreeMap, or get, get_mut, remove, and the Index/ IndexMut implementations for key lookups — see the Indexing section below.

Method	Returns
`as_map`	`Result<&BTreeMap<Value, Value>>`
`as_map_mut`	`Result<&mut BTreeMap<Value, Value>>`
`into_map`	`Result<BTreeMap<Value, Value>>`

use cbor_core::{Value, map};

let v = map! { "name" => "Alice", "age" => 30 };
assert_eq!(v["name"].as_str().unwrap(), "Alice");

// Modify in place
let mut v = map! { "count" => 1 };
v.insert("count", 2);
assert_eq!(v["count"].to_u32().unwrap(), 2);

§Indexing

Arrays and maps share a uniform interface for element access, summarized below. Entries with a shaded “Panics” cell never panic under any inputs.

Method	Returns	Non-collection receiver	Invalid / missing key
`len`	`Option<usize>`	`None`	—
`contains`	`bool`	`false`	`false`
`get`	`Option<&Value>`	`None`	`None`
`get_mut`	`Option<&mut Value>`	`None`	`None`
`insert`	`Option<Value>` (arrays: always `None`)	panics	array: panics; map: inserts
`remove`	`Option<Value>`	panics	array: panics; map: `None`
`append`	`()`	panics (maps included)	—
`v[key]`, `v[key] = …`	`&Value`, `&mut Value`	panics	panics

The methods split into two flavors:

Soft — len, contains, get, and get_mut: never panic. They return Option/bool and treat a wrong-type receiver the same as a missing key.
Hard — insert, remove, append, and the [] operators: panic when the receiver is not an array or map, when an array index is not a valid usize (negative, non-integer key), or when the index is out of range. This mirrors Vec and BTreeMap.

All keyed methods accept any type implementing Into<ValueKey>: integers (for array indices and integer map keys), &str, &[u8], &Value, and the primitive CBOR types. insert takes Into<Value> for the key, since a map insert has to own the key anyway.

All methods see through tags transparently — operating on a Tag dispatches to the innermost tagged content.

§Arrays

The key is always a usize index. Valid ranges differ by method:

get, get_mut, contains, remove, and v[i] require i to be in 0..len. get/get_mut/contains return None/false for invalid or out-of-range indices; remove and v[i] panic.
insert accepts 0..=len (appending at len is allowed) and shifts subsequent elements right. It always returns None, and panics if the index is invalid or out of range.
append pushes to the end in O(1) and never cares about an index.
insert and remove shift elements, which is O(n) and can be slow for large arrays. Prefer append when order at the end is all you need.
To replace an element in place (O(1), no shift), assign through get_mut or v[i] = ….

§Maps

The key is any CBOR-convertible value:

insert returns the previous value if the key was already present, otherwise None — matching BTreeMap::insert.
remove returns the removed value, or None if the key was absent. It never panics on a missing key (maps have no notion of an out-of-range key).
get, get_mut, and contains return None/false for missing keys; v[key] panics.
append is an array-only operation and panics when called on a map.

§Example

use cbor_core::{Value, array, map};

// --- arrays ---
let mut a = array![10, 30];
a.insert(1, 20);                          // shift-insert at index 1
a.append(40);                             // push to end
assert_eq!(a.len(), Some(4));
a[0] = Value::from(99);                   // O(1) in-place replace
assert_eq!(a.remove(0).unwrap().to_u32().unwrap(), 99);
assert!(a.contains(0));
assert_eq!(a.get(5), None);               // out of range: soft miss

// --- maps ---
let mut m = map! { "x" => 10 };
assert_eq!(m.insert("y", 20), None);      // new key
assert_eq!(m.insert("x", 99).unwrap().to_u32().unwrap(), 10);
assert_eq!(m["x"].to_u32().unwrap(), 99);
assert_eq!(m.remove("missing"), None);    // missing key: no panic
assert!(!m.contains("missing"));

§Tags

A tag wraps another value with a numeric label (e.g. tag 1 for epoch timestamps, tag 32 for URIs). Tags can be nested.

Method	Returns	Notes
`tag_number`	`Result<u64>`	Tag number
`tag_content`	`Result<&Value>`	Borrowed content
`tag_content_mut`	`Result<&mut Value>`	Mutable content
`as_tag`	`Result<(u64, &Value)>`	Both parts
`as_tag_mut`	`Result<(u64, &mut Value)>`	Mutable content
`into_tag`	`Result<(u64, Value)>`	Consuming

Use untagged to look through tags without removing them, remove_tag to strip the outermost tag, or remove_all_tags to strip all layers at once.

use cbor_core::Value;

// Create a tagged value (tag 32 = URI)
let mut uri = Value::tag(32, "https://example.com");

// Inspect
let (tag_num, content) = uri.as_tag().unwrap();
assert_eq!(tag_num, 32);
assert_eq!(content.as_str().unwrap(), "https://example.com");

// Look through tags without removing them
assert_eq!(uri.untagged().as_str().unwrap(), "https://example.com");

// Strip the tag in place
let removed = uri.remove_tag();
assert_eq!(removed, Some(32));
assert_eq!(uri.as_str().unwrap(), "https://example.com");

Accessor methods see through tags transparently: calling as_str() on a tagged text string works without manually unwrapping the tag first. This applies to all accessors (to_*, as_*, into_*).

use cbor_core::Value;

let uri = Value::tag(32, "https://example.com");
assert_eq!(uri.as_str().unwrap(), "https://example.com");

// Nested tags are also transparent
let nested = Value::tag(100, Value::tag(200, 42));
assert_eq!(nested.to_u32().unwrap(), 42);

Big integers are internally represented as tagged byte strings (tags 2 and 3). The integer accessors recognise these tags and decode the bytes automatically, even when wrapped in additional custom tags. Byte-level accessors like as_bytes() also see through tags, so calling as_bytes() on a big integer returns the raw payload bytes.

If a tag is removed via remove_tag, remove_all_tags, or by consuming through into_tag, the value becomes a plain byte string and can no longer be read as an integer.

§Type introspection

data_type returns a DataType enum for lightweight type checks without matching on the full enum.

use cbor_core::Value;

let v = Value::from(3.14);
assert!(v.data_type().is_float());

Variants§

§

SimpleValue(SimpleValue)

Simple value such as null, true, or false (major type 7).

In CBOR, booleans and null are simple values, not distinct types. A Value::from(true) is stored as SimpleValue(21) and is accessible through both to_bool and to_simple_value.

let sv = Value::null();
assert!(sv.data_type().is_simple_value() && sv.data_type().is_null());

let sv = Value::new(false);
assert!(sv.data_type().is_simple_value() && sv.data_type().is_bool());

§

Unsigned(u64)

Unsigned integer (major type 0). Stores values 0 through 2^64-1.

let v = Value::new(42);

§

Negative(u64)

Negative integer (major type 1). The actual value is -1 - n, covering -1 through -2^64.

let v = Value::new(-42);

§

Float(Float)

IEEE 754 floating-point number (major type 7, additional info 25-27).

let v = Value::new(1.234);

§

ByteString(Vec<u8>)

Byte string (major type 2).

let v = Value::new(b"this is a byte string");

§

TextString(String)

UTF-8 text string (major type 3).

let v = Value::new("Rust + CBOR::Core");

§

Array(Vec<Value>)

Array of data items (major type 4).

use cbor_core::array;
let v = array![1, 2, 3, "text", b"bytes", true, 1.234, array![4,5,6]];

§

Map(BTreeMap<Value, Value>)

Map of key-value pairs in canonical order (major type 5).

use cbor_core::{map, array};
let v = map!{"answer" => 42, array![1,2,3] => "arrays as keys" };

§

Tag(u64, Box<Value>)

Tagged data item (major type 6). The first field is the tag number, the second is the enclosed content.

let v = Value::tag(0, "1955-11-12T22:04:00-08:00");

Enum Value Copy item path

§Creating values

§const constructors

§Encoding and decoding

§Accessors

§Simple values

§Integers

§Floats

§Byte strings

§Text strings

§Arrays

§Maps

§Indexing

§Arrays

§Maps

§Example

§Tags

§Type introspection

Variants§

SimpleValue(SimpleValue)

Unsigned(u64)

Negative(u64)

Float(Float)

ByteString(Vec<u8>)

TextString(String)

Array(Vec<Value>)

Map(BTreeMap<Value, Value>)

Tag(u64, Box<Value>)

Implementations§

impl Value

pub fn to_f16(&self) -> Result<f16>

impl Value

pub const fn null() -> Self

pub const fn simple_value(value: u8) -> Self

§Panics

pub const fn from_bool(value: bool) -> Self

pub const fn from_u64(value: u64) -> Value

pub const fn from_i64(value: i64) -> Value

pub const fn from_f32(value: f32) -> Value

pub const fn from_f64(value: f64) -> Value

pub const fn from_payload(payload: u64) -> Value

pub fn new(value: impl TryInto<Value>) -> Self

§Panics

pub fn byte_string(value: impl Into<Vec<u8>>) -> Self

pub fn text_string(value: impl Into<String>) -> Self

pub fn date_time(value: impl TryInto<DateTime>) -> Self

§Panics

pub fn epoch_time(value: impl TryInto<EpochTime>) -> Self

§Panics

pub fn float(value: impl Into<Float>) -> Self

pub fn array(array: impl Into<Array>) -> Self

pub fn map(map: impl Into<Map>) -> Self

pub fn tag(number: u64, content: impl Into<Value>) -> Self

impl Value

pub fn decode(bytes: impl AsRef<[u8]>) -> Result<Self>

pub fn decode_hex(hex: impl AsRef<[u8]>) -> Result<Self>

pub fn read_from(reader: impl Read) -> IoResult<Self>

pub fn read_hex_from(reader: impl Read) -> IoResult<Self>

impl Value

pub fn encode(&self) -> Vec<u8> ⓘ

pub fn encode_hex(&self) -> String

pub fn write_to(&self, writer: impl Write) -> Result<()>

pub fn write_hex_to(&self, writer: impl Write) -> Result<()>

impl Value

pub const fn data_type(&self) -> DataType

pub fn take(&mut self) -> Self

pub fn replace(&mut self, value: Self) -> Self

impl Value

pub const fn to_bool(&self) -> Result<bool>

pub const fn to_simple_value(&self) -> Result<u8>

pub fn to_u8(&self) -> Result<u8>

pub fn to_u16(&self) -> Result<u16>

pub fn to_u32(&self) -> Result<u32>

pub fn to_u64(&self) -> Result<u64>

pub fn to_u128(&self) -> Result<u128>

pub fn to_usize(&self) -> Result<usize>

pub fn to_i8(&self) -> Result<i8>

pub fn to_i16(&self) -> Result<i16>

pub fn to_i32(&self) -> Result<i32>

pub fn to_i64(&self) -> Result<i64>

Enum Value

§`const` constructors