Struct Value 

pub struct Value { /* private fields */ }

A dynamic value.

A value is made of its Kind, which holds the actual data, and optional Meta data. The value dereferences to its kind, which is where the accessors are defined and what is matched on:

use deser_value::{value, Kind};

let value = value!({"name": "Jane", "roles": ["admin"]});
assert_eq!(value["name"].as_str(), Some("Jane"));

match &*value["roles"] {
    Kind::Seq(roles) => assert_eq!(roles.len(), 1),
    _ => unreachable!(),
}

Meta Data

Values retain information that is not part of the data model. This is held in the Meta of a value, which is only allocated if there is such information:

• The event data of the value, for instance CBOR tags or formatting hints. It’s captured when the value is deserialized and attached again when it’s serialized.
• The Span of the value in the input, if the format tracks locations. Values that are deserialized from a value with spans report errors at the original location.

Meta data is ignored when values are compared or hashed and it’s not shown in the debug output.

Numbers

Integers are held as Kind::U64 and Kind::I64. Values created by this crate hold non-negative integers as U64 and integers which do not fit into 64 bits (u128 and i128) as Kind::Ext. Integers compare by their value: I64(1) is equal to U64(1). Floats compare by their bits, which means that NaN is equal to itself and -0.0 is not equal to 0.0.

Extensions

Values which extend the data model (see deser::ext) are held as Kind::Ext. They retain their type and are serialized as extension values again. The accessors (such as as_str) look at them through their fallback.

Nesting

All operations on values (including dropping, cloning, comparing and formatting) are implemented without recursion, deeply nested values do not overflow the stack.

Implementations

impl Value

pub const fn null() -> Value

Creates a null value.

pub const fn new(kind: Kind) -> Value

Creates a value from its kind.

pub fn ext<T: Extension>(value: T) -> Value

Creates a value holding an extension value.

use deser::ext::Uuid;
use deser_value::Value;

let value = Value::ext(Uuid([0; 16]));
assert!(value.downcast_ext::<Uuid>().is_some());

pub fn bytes<B: Into<Vec<u8>>>(data: B) -> Value

Creates a value holding bytes.

pub fn kind(&self) -> &Kind

Returns the kind of the value.

pub fn kind_mut(&mut self) -> &mut Kind

Returns the kind of the value mutably.

pub fn into_kind(self) -> Kind

Converts the value into its kind, discarding the meta data.

pub fn into_parts(self) -> (Kind, Option<Meta>)

Converts the value into its kind and meta data.

pub fn meta(&self) -> Option<&Meta>

Returns the meta data of the value, if there is any.

pub fn meta_mut(&mut self) -> &mut Meta

Returns the meta data of the value mutably.

Empty meta data is created if the value has none.

pub fn take_meta(&mut self) -> Option<Meta>

Removes the meta data of the value and returns it.

pub fn set_meta(&mut self, meta: Option<Meta>)

Sets the meta data of the value.

pub fn span(&self) -> Option<&Span>

Returns the span of the value in the input.

This is a shortcut for the span of the Meta.

pub fn event_data(&self) -> Option<&EventData>

Returns the event data of the value.

This is a shortcut for the event data of the Meta.

pub fn take(&mut self) -> Value

Takes the value out, leaving null in its place.

Methods from Deref<Target = Kind>

pub fn name(&self) -> &str

Returns the human readable name of the kind.

pub fn is_null(&self) -> bool

Returns true if this is null.

Extension values that fall back to null count as null.

pub fn as_bool(&self) -> Option<bool>

Returns the value of a bool.

pub fn as_u64(&self) -> Option<u64>

Returns the value of an integer if it fits into u64.

pub fn as_i64(&self) -> Option<i64>

Returns the value of an integer if it fits into i64.

pub fn as_u128(&self) -> Option<u128>

Returns the value of an integer if it fits into u128.

pub fn as_i128(&self) -> Option<i128>

Returns the value of an integer if it fits into i128.

pub fn as_f64(&self) -> Option<f64>

Returns the value of a number as f64.

Integers are converted, which can lose precision.

pub fn as_char(&self) -> Option<char>

Returns the value of a char.

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

Returns the value of a string.

For extension values this returns the fallback if it’s a string that borrows from the value.

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

Returns the data of bytes.

pub fn as_seq(&self) -> Option<&Seq>

Returns the sequence.

pub fn as_seq_mut(&mut self) -> Option<&mut Seq>

Returns the sequence mutably.

pub fn as_map(&self) -> Option<&Map>

Returns the map.

pub fn as_map_mut(&mut self) -> Option<&mut Map>

Returns the map mutably.

pub fn as_ext(&self) -> Option<&ExtValue<'static>>

Returns the extension value.

pub fn downcast_ext<T: Extension>(&self) -> Option<&T>

Returns the extension value if it’s of type T.

For extensions that borrow, use downcast_ext_value.

pub fn downcast_ext_value<K: BorrowedExtension>(&self) -> Option<&K::Value<'_>>

Returns the extension value if it’s of the extension with the key K.

See BorrowedExtension.

use deser::ext::Number;
use deser_value::Value;

let value: Value =
    deser_json::from_str("0.10000000000000000001").unwrap();
let number = value.downcast_ext_value::<Number>().unwrap();
assert_eq!(number.as_str(), "0.10000000000000000001");

pub fn is_str(&self) -> bool

Returns true if this is a string.

This is also true for lexical values.

pub fn is_lexical(&self) -> bool

Returns true if this is a lexical value.

pub fn is_seq(&self) -> bool

Returns true if this is a sequence.

pub fn is_map(&self) -> bool

Returns true if this is a map.

pub fn get<I: ValueIndex>(&self, index: I) -> Option<&Value>

Looks up a value in a sequence (by index) or a map (by key).

use deser_value::value;

let value = value!({"items": [1, 2], 42: "answer"});
assert_eq!(value.get("items").and_then(|x| x.get(1)), Some(&value!(2)));
assert_eq!(value.get(&value!(42)), Some(&value!("answer")));
assert_eq!(value.get("missing"), None);

pub fn get_mut<I: ValueIndex>(&mut self, index: I) -> Option<&mut Value>

Looks up a value in a sequence (by index) or a map (by key) mutably.

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Value

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

Formats the value using the given formatter.

impl Default for Value

fn default() -> Value

Returns the “default value” for a type.

impl Deref for Value

type Target = Kind

The resulting type after dereferencing.

fn deref(&self) -> &Kind

Dereferences the value.

impl DerefMut for Value

fn deref_mut(&mut self) -> &mut Kind

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Value

fn deserialize_update<'out>( value: &'out mut Self, state: &mut State, ) -> SinkHandle<'out, 'de>

Updates the value: a map merges the data into it if it’s a map (the values of keys that exist are replaced), all other values are replaced.

fn deserialize_into<'out>( out: &'out mut Option<Self>, state: &mut State, ) -> SinkHandle<'out, 'de>

Creates a sink that deserializes the value into the given slot.

fn expecting() -> Cow<'static, str>

Returns what the value expects, for error messages.

fn deserialize_atom( slot: &mut Slot<T, Self>, atom: Atom<'_>, state: &mut State, ) -> Result<(), Error>

Deserializes an atom into the slot.

fn deserialize_borrowed_atom( slot: &mut Slot<T, Self>, atom: Atom<'de>, state: &mut State, ) -> Result<(), Error>

Deserializes an atom that borrows from the data being deserialized into the slot.

fn describe_type(d: &mut dyn Describe)

Describes the Rust shape of the type.

fn initial_value() -> Option<T>

Provides the value of a missing struct field.

impl Eq for Value

impl From<&String> for Value

fn from(value: &String) -> Value

Converts to this type from the input type.

impl<T: Clone + Into<Value>> From<&[T]> for Value

fn from(value: &[T]) -> Value

Converts to this type from the input type.

impl From<&str> for Value

fn from(value: &str) -> Value

Converts to this type from the input type.

impl From<()> for Value

fn from(_: ()) -> Value

Converts to this type from the input type.

impl From<Bytes<'_>> for Value

fn from(value: Bytes<'_>) -> Value

Converts to this type from the input type.

impl From<Cow<'_, str>> for Value

fn from(value: Cow<'_, str>) -> Value

Converts to this type from the input type.

impl From<ExtValue<'_>> for Value

fn from(value: ExtValue<'_>) -> Value

Creates a value from an extension value.

Integers of extensions (u128 and i128) which fit into 64 bits are converted into U64 and I64.

impl From<Kind> for Value

fn from(kind: Kind) -> Value

Converts to this type from the input type.

impl From<Map> for Value

fn from(value: Map) -> Value

Converts to this type from the input type.

impl<T: Into<Value>> From<Option<T>> for Value

fn from(value: Option<T>) -> Value

Converts to this type from the input type.

impl From<Seq> for Value

fn from(value: Seq) -> Value

Converts to this type from the input type.

impl From<String> for Value

fn from(value: String) -> Value

Converts to this type from the input type.

impl<T: Into<Value>> From<Vec<T>> for Value

fn from(value: Vec<T>) -> Value

Converts to this type from the input type.

impl From<bool> for Value

fn from(value: bool) -> Value

Converts to this type from the input type.

impl From<char> for Value

fn from(value: char) -> Value

Converts to this type from the input type.

impl From<f32> for Value

fn from(value: f32) -> Value

Converts to this type from the input type.

impl From<f64> for Value

fn from(value: f64) -> Value

Converts to this type from the input type.

impl From<i8> for Value

fn from(value: i8) -> Value

Converts to this type from the input type.

impl From<i16> for Value

fn from(value: i16) -> Value

Converts to this type from the input type.

impl From<i32> for Value

fn from(value: i32) -> Value

Converts to this type from the input type.

impl From<i64> for Value

fn from(value: i64) -> Value

Converts to this type from the input type.

impl From<i128> for Value

fn from(value: i128) -> Value

Converts to this type from the input type.

impl From<isize> for Value

fn from(value: isize) -> Value

Converts to this type from the input type.

impl From<u8> for Value

fn from(value: u8) -> Value

Converts to this type from the input type.

impl From<u16> for Value

fn from(value: u16) -> Value

Converts to this type from the input type.

impl From<u32> for Value

fn from(value: u32) -> Value

Converts to this type from the input type.

impl From<u64> for Value

fn from(value: u64) -> Value

Converts to this type from the input type.

impl From<u128> for Value

fn from(value: u128) -> Value

Converts to this type from the input type.

impl From<usize> for Value

fn from(value: usize) -> Value

Converts to this type from the input type.

impl<K: Into<Value>, V: Into<Value>> FromIterator<(K, V)> for Value

fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Value

Creates a value from an iterator.

impl<T: Into<Value>> FromIterator<T> for Value

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Value

Creates a value from an iterator.

impl Hash for Value

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<I: ValueIndex> Index<I> for Value

fn index(&self, index: I) -> &Value

Looks up a value in a sequence (by index) or a map (by key).

Returns null if the value does not exist.

type Output = Value

The returned type after indexing.

impl<I: ValueIndex> IndexMut<I> for Value

fn index_mut(&mut self, index: I) -> &mut Value

Looks up a value in a sequence (by index) or a map (by key) mutably.

Keys that do not exist are inserted with null and a null value turns into a map if it’s indexed by a key.

Panics

Panics if the index is out of bounds, or if the value cannot be indexed by the index.

impl MapKey for Value

impl PartialEq for Value

fn eq(&self, other: &Value) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<&str> for Value

fn eq(&self, other: &&str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<String> for Value

fn eq(&self, other: &String) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<bool> for Value

fn eq(&self, other: &bool) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<f32> for Value

fn eq(&self, other: &f32) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<f64> for Value

fn eq(&self, other: &f64) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<i8> for Value

fn eq(&self, other: &i8) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<i16> for Value

fn eq(&self, other: &i16) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<i32> for Value

fn eq(&self, other: &i32) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<i64> for Value

fn eq(&self, other: &i64) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<isize> for Value

fn eq(&self, other: &isize) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<str> for Value

fn eq(&self, other: &str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<u8> for Value

fn eq(&self, other: &u8) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<u16> for Value

fn eq(&self, other: &u16) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<u32> for Value

fn eq(&self, other: &u32) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<u64> for Value

fn eq(&self, other: &u64) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<usize> for Value

fn eq(&self, other: &usize) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Value

fn serialize<'a>(value: &'a Self, state: &mut State) -> Result<Emit<'a>, Error>

Serializes the value.

fn container_shape(value: &Self) -> ContainerShape

Returns the shape of the value if it’s a map or sequence.

fn is_optional(value: &Self) -> bool

Checks if the value represents an optional value.

fn finish(value: &T, state: &mut State) -> Result<(), Error>

Invoked after the serialization finished.

fn describe(value: &T, d: &mut dyn Describe)

Describes the Rust shape of the value.

impl ValueIndex for Value