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:

Constructor	Builds
`Value::null()`	Null simple value
`Value::simple_value(v)`	Arbitrary simple value
`Value::float(v)`	Float in shortest CBOR form
`Value::array(v)`	Array from slice, `Vec`, or fixed-size array
`Value::map(v)`	Map from `BTreeMap`, `HashMap`, slice of pairs, etc.
`Value::tag(n, v)`	Tagged value

§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);

For streaming use, write_to and read_from operate on any io::Write / io::Read.

§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 impls — 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 impls 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.

§

Unsigned(u64)

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

§

Negative(u64)

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

§

Float(Float)

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

§

ByteString(Vec<u8>)

Byte string (major type 2).

§

TextString(String)

UTF-8 text string (major type 3).

§

Array(Vec<Value>)

Array of data items (major type 4).

§

Map(BTreeMap<Value, Value>)

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

§

Tag(u64, Box<Value>)

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

Enum Value Copy item path

§Creating values

§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 fn take(&mut self) -> Self

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

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

pub fn encode_hex(&self) -> String

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>

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

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

pub const fn null() -> Self

pub fn simple_value(value: impl TryInto<SimpleValue>) -> Self

§Panics

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

pub const fn data_type(&self) -> DataType

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>

pub fn to_i128(&self) -> Result<i128>

pub fn to_isize(&self) -> Result<isize>

pub fn to_f32(&self) -> Result<f32>

pub fn to_f64(&self) -> Result<f64>

pub fn to_system_time(&self) -> Result<SystemTime>

pub fn as_bytes(&self) -> Result<&[u8]>

pub const fn as_bytes_mut(&mut self) -> Result<&mut Vec<u8>>

pub fn into_bytes(self) -> Result<Vec<u8>>

pub fn as_str(&self) -> Result<&str>

pub const fn as_string_mut(&mut self) -> Result<&mut String>

pub fn into_string(self) -> Result<String>

pub fn as_array(&self) -> Result<&[Value]>

pub const fn as_array_mut(&mut self) -> Result<&mut Vec<Value>>

pub fn into_array(self) -> Result<Vec<Value>>

pub const fn as_map(&self) -> Result<&BTreeMap<Value, Value>>

Enum Value

impl<const LIMBS: usize> From<&Int<LIMBS>> for Value
where Uint<LIMBS>: Encoding,

impl<const LIMBS: usize> From<&NonZero<Int<LIMBS>>> for Value
where Uint<LIMBS>: Encoding,

impl<const LIMBS: usize> From<&NonZero<Uint<LIMBS>>> for Value
where Uint<LIMBS>: Encoding,

impl<const LIMBS: usize> From<&Uint<LIMBS>> for Value
where Uint<LIMBS>: Encoding,