Enum kserd::Value

pub enum Value<'a> {
    Unit,
    Bool(bool),
    Num(Number),
    Str(Kstr<'a>),
    Barr(Barr<'a>),
    Tuple(Vec<Kserd<'a>>),
    Cntr(BTreeMap<Kstr<'a>, Kserd<'a>>),
    Seq(Vec<Kserd<'a>>),
    Map(BTreeMap<Kserd<'a>, Kserd<'a>>),
}

The value of a Kserd.

Value captures primitive types (units, booleans, numbers, strings, byte arrays), which act as leaves, along with nested structures (tuples, containers, sequences, and maps).

Sequences and maps are simply aliases for vectors/lists, and hashmaps/dictionaries respectively. Keyed structures are backed by BTreeMap so keys are lexiographically sorted. Tuples and containers are aliases for tuples/newtype structures and enums, and structures respectively.

Value tries to avoid owning data, especially larger data such as strings and byte arrays. The use of clone-on-write smart pointers are used to facilitate borrowing until mutation is required. Value has numerous convenience methods to facilitate constructing, reading, and mutating an object.

Examples

Use the methods to quickly see the data if the type is known. Mutating can be done directly.

let mut val = Value::new_str("Hi");
val.str_mut().map(|s| {
    s.pop();
    s.push_str("ello, world!");
});
assert_eq!(val.str(), Some("Hello, world!"));

Variants

Unit

A unit value ().

Bool(bool)

A boolean value.

Num(Number)

A numerical value. See Number.

Str(Kstr<'a>)

A string value. Can be borrowed or owned. See Kstr.

Barr(Barr<'a>)

A byte array value. Can be borrowed or owned. See Barr.

Tuple(Vec<Kserd<'a>>)

A tuple value.

A tuple is a hetrogeneous sequence of unnamed objects. It shares the same in-memory representation as a sequence but has different formatting syntax. Tuples represent not only anonymous tuples ((u32, u32, u32)) but also newtype structs and enums (ie Point3d(u32, u32, u32)).

Cntr(BTreeMap<Kstr<'a>, Kserd<'a>>)

A container value.

A container is a hetrogeneous collection of named objects. Containers are akin to structs.

Seq(Vec<Kserd<'a>>)

A sequence of values.

A sequence is a homogeneous sequence of unnamed objects.

Map(BTreeMap<Kserd<'a>, Kserd<'a>>)

A map of values.

A map is a homogeneous mapping of keys to values.

Methods

impl Value<'static>

Static lifetime constructors.

pub fn new_num<T: NumberType>(value: T) -> Self

A new number value. The trait NumberType is implemented on all Rust primitive numbers so number literals can be used.

Example

let value = Value::new_num(123456);
assert_eq!(value.uint(), Some(123456));

let value = Value::new_num(-123456);
assert_eq!(value.int(), Some(-123456));

let value = Value::new_num(3.14);
assert_eq!(value.float(), Some(3.14));

pub const fn new_string(string: String) -> Self

A new string value. The ownership of the string is transferred and as such the Value has a static lifetime.

Example

let value = Value::new_string(String::from("Hello, world!"));
assert_eq!(value.str(), Some("Hello, world!"));

pub const fn new_barrv(byte_array: Vec<u8>) -> Self

A new byte array value. The ownership of the vector is transferred and as such the Value has a static lifetime.

Example

let value = Value::new_barrv(vec![0,1,2,3]);
assert_eq!(value.barr(), Some([0,1,2,3].as_ref()));

impl<'a> Value<'a>

General lifetime constructors.

pub const fn new_str(string: &'a str) -> Self

A new string value. The Value borrows the string and has the same lifetime.

Example

let value = Value::new_str("Hello, world!");
assert_eq!(value.str(), Some("Hello, world!"));

pub const fn new_barr(byte_array: &'a [u8]) -> Self

A new byte array value. The Value borrows the array and has the same lifetime.

Example

let value = Value::new_barr([0,1,2,5,10].as_ref());
assert_eq!(value.barr(), Some([0,1,2,5,10].as_ref()));

pub fn new_cntr<I, S>(iter: I) -> Result<Self, InvalidFieldName> where
    S: Into<Kstr<'a>>,
    I: IntoIterator<Item = (S, Kserd<'a>)>, 

Construct a new container value from a list of field-value pairs.

Example

let pass = Value::new_cntr(vec![
    ("a", Kserd::new_num(0))
]).unwrap();

let fail = Value::new_cntr(vec![
    ("1 wrong/name", Kserd::new_num(0))
]);
assert_eq!(fail.is_err(), true);

pub fn new_map<I>(iter: I) -> Self where
    I: IntoIterator<Item = (Kserd<'a>, Kserd<'a>)>, 

Construct a new map value from a list of key-value pairs.

Example

let value = Value::new_map(vec![
    (Kserd::new_unit(), Kserd::new_num(0))
]);

impl<'a> Value<'a>

Convenience methods for accessing values straight from the Value enum.

pub fn unit(&self) -> bool

Value is a unit value (Value::Unit).

Example

let value = Value::Unit;
assert_eq!(value.unit(), true);

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

Value is a boolean value.

Example

let value = Value::Bool(true);
assert_eq!(value.bool(), Some(true));

pub fn bool_mut(&mut self) -> Option<&mut bool>

Value is a boolean value. Can be altered.

Example

let mut value = Value::Bool(false);
value.bool_mut().map(|x| *x = true);
assert_eq!(value.bool(), Some(true));

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

Value is a string with a single character.

Example

let value = Value::new_str("A");
assert_eq!(value.ch(), Some('A'));

let value = Value::new_str("Hello, world!");
assert_eq!(value.ch(), None);

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

Value is an unsigned integer.

Example

let value = Value::new_num(123456);
assert_eq!(value.uint(), Some(123456));

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

Value is a signed integer. A positive integer can be both signed and unsigned up to i128::max_value().

Example

let value = Value::new_num(-123456);
assert_eq!(value.int(), Some(-123456));

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

Value is a floating point number. Both signed and unsigned integers can be represented as floats.

Example

let value = Value::new_num(-3.14);
assert_eq!(value.float(), Some(-3.14));

pub fn num_mut(&mut self) -> Option<&mut Number>

Value is a numerical value, and can be altered.

Example

let mut value = Value::new_num(123456);
value.num_mut().map(|x| *x = Number::from(100));
assert_eq!(value.uint(), Some(100));

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

Value is a string.

Example

let value = Value::new_str("Hello, world!");
assert_eq!(value.str(), Some("Hello, world!"));

pub fn str_mut(&mut self) -> Option<&mut String>

Value is a string. Can be altered.

Clones string value if not owned.

Example

let mut value = Value::new_str("Hello");
value.str_mut().map(|x| { x.push_str(", world!"); });
assert_eq!(value.str(), Some("Hello, world!"));

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

Value is a byte array.

Example

let value = Value::new_barr([0,1,2,5,10].as_ref());
assert_eq!(value.barr(), Some([0,1,2,5,10].as_ref()));

pub fn barr_mut(&mut self) -> Option<&mut Vec<u8>>

Value is a byte array. Can be altered.

Clones data if not already owned.

Example

let mut value = Value::new_barr([0,1,2].as_ref());
value.barr_mut().map(|x| { x.push(3); });
assert_eq!(value.barr(), Some([0,1,2,3].as_ref()));

impl<'a> Value<'a>

Conversions.

pub fn into_owned(self) -> Value<'static>

Clones all data to make a static Value.

pub fn mk_brw(&self) -> Value

Makes a copy of this Value that references data in the this Value.

This is particularly useful if you want to gaurantee that all data is of the borrowed variety when decoding back to a data structure (see Decoder for explanation).

There is a performance penalty as nested structures have to be rebuilt.

Example

let value = Value::new_string("Hello, world!".to_owned());
let brwed = value.mk_brw();
assert_eq!(value, brwed);

Trait Implementations

impl<'a> Clone for Value<'a>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Value<'a>

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

Formats the value using the given formatter.

impl<'a> Eq for Value<'a>

impl<'a> Ord for Value<'a>

fn cmp(&self, other: &Value<'a>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<'a> PartialEq<Value<'a>> for Value<'a>

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Value<'a>) -> bool

This method tests for !=.

impl<'a> PartialOrd<Value<'a>> for Value<'a>

fn partial_cmp(&self, other: &Value<'a>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Value<'a>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Value<'a>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Value<'a>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Value<'a>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> StructuralEq for Value<'a>

impl<'a> StructuralPartialEq for Value<'a>