Struct kserd::ds::Kserd

pub struct Kserd<'a> {
    pub id: Option<Kstr<'a>>,
    pub val: Value<'a>,
}

The atomic value.

Kserd contains an optional identity (id), and the Value. Taken together the Kserd object can describe (almost) all Rust data structures. The identity can be mostly ignored for self-explanatory data such as primitives. It can be used to name structures, and plays a special role in unit structs and enum variants.

Kserd dereferences mutably to Value so all reading and mutating methods on Value can use directly. It is encouraged to use the methods rather than accessing the fields directly.

Kserd implements ordering and equality, it is important to note that ordering and equality is done only on the value, the identity is ignored.

Example

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

let mut kserd = Kserd::new_str("Hi");

// access the data without needing to pattern match
assert_eq!(kserd.str(), Some("Hi"));
// using ctors will name your ds for you
assert_eq!(kserd.id(), Some("str"));
// if not of the type, nothing returned.
assert_eq!(kserd.int(), None);

kserd.str_mut().map(|s| {
    s.pop();
    s.push_str("ello, world!");
}); // mutate directly.
    // this method has the additional effect of cloning the string.
assert_eq!(kserd.str(), Some("Hello, world!"));

Fields

id: Option<Kstr<'a>>

The identity of the value.

This can be optional. Typically the identity is something like the struct or enum name.

val: Value<'a>

The Value.

This store the actual value, which comprises of primitive types or more complex nested types such as sequences or maps.

Implementations

impl Kserd<'static>

Static lifetime constructors. These do not need a Serialize trait.

pub const fn new_unit() -> Self

A new unit value ().

Example

let kserd = Kserd::new_unit();
assert_eq!(kserd.unit(), true);
assert_eq!(kserd.id(), None);

pub fn new_bool(value: bool) -> Self

A new boolean value.

Example

let kserd = Kserd::new_bool(true);
assert_eq!(kserd.bool(), Some(true));
assert_eq!(kserd.id(), Some("bool"));

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 kserd = Kserd::new_num(123456);
assert_eq!(kserd.uint(), Some(123456));

let kserd = Kserd::new_num(-123456);
assert_eq!(kserd.int(), Some(-123456));

let kserd = Kserd::new_num(3.14);
assert_eq!(kserd.float(), Some(3.14));

pub fn new_string(string: String) -> Self

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

Example

let kserd = Kserd::new_string(String::from("Hello, world!"));
assert_eq!(kserd.str(), Some("Hello, world!"));
assert_eq!(kserd.id(), Some("String"));

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

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

Example

let kserd = Kserd::new_barrv(vec![0,1,2,3]);
assert_eq!(kserd.barr(), Some([0,1,2,3].as_ref()));
assert_eq!(kserd.id(), Some("ByteVec"));

impl<'a> Kserd<'a>

General lifetime contructors. These do not need a Serialize trait.

pub const fn new(value: Value<'a>) -> Self

A new Kserd with the specified Value. No identity is ascribed to the Kserd.

Example

let kserd = Kserd::new(Value::Unit);
assert_eq!(kserd.val, Value::Unit);
assert_eq!(kserd.id, None);

pub fn with_id<S: Into<Kstr<'a>>>(
    identity: S,
    value: Value<'a>
) -> Result<Self, InvalidId>

A new Kserd with a specified identity and Value.

The identity is taken as a Kstr, meaning it can be a reference or owned. String and &str can be used as the identity. The identity must also be valid, that is, it cannot contain certain characters or Err will be returned.

It is recommended to construct Kserd in this manner rather than manually via setting the id and val fields as an invalid identity will not parse back from text.

Example

let kserd = Kserd::with_id("an-identity", Value::Bool(true)).unwrap();
assert_eq!(kserd.bool(), Some(true));
assert_eq!(kserd.id(), Some("an-identity"));

let kserd = Kserd::with_id("<an,> in(valid.)/{identity}\\=", Value::Unit);
assert_eq!(kserd.is_err(), true);

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

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

Example

let kserd = Kserd::new_str("Hello, world!");
assert_eq!(kserd.str(), Some("Hello, world!"));
assert_eq!(kserd.id(), Some("str"));

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

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

Example

let kserd = Kserd::new_barr([0,1,2,5,10].as_ref());
assert_eq!(kserd.barr(), Some([0,1,2,5,10].as_ref()));
assert_eq!(kserd.id(), Some("barr"));

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 Kserd from a list of field-value pairs.

Example

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

let fail = Kserd::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 kserd = Kserd::new_map(vec![
    (Kserd::new_unit(), Kserd::new_num(0))
]);

impl<'a> Kserd<'a>

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

The identity. Same as the .id field but mapped as a &str.

Example

let kserd = Kserd::with_id("Hello", Value::Unit).unwrap();
assert_eq!(kserd.id(), Some("Hello"));

impl<'a> Kserd<'a>

Conversions.

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

Clones all data to make a static Kserd.

pub fn mk_brw(&self) -> Kserd<'_>

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

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 kserd = Kserd::new_string("Hello, world!".to_owned());
let brwed = kserd.mk_brw();
assert_eq!(kserd, brwed);

impl Kserd<'static>

pub fn enc<T: Serialize>(data: &T) -> Result<Self, Error>

Encode T into a Kserd.

Requires the encode feature.

Convenience function for data.serialize(Encoder).

See Encoder for usage.

impl<'a> Kserd<'a>

pub fn decode<T: Deserialize<'a>>(self) -> Result<T, Error>

Attempt to decode a Kserd into type T.

Requires the encode feature.

Convenience function for <T as Deserialize>::deserialize(Decoder(self)).

See Decoder for usage.

impl<'a> Kserd<'a>

String representation.

pub fn as_str(&self) -> String

Format the Kserd as a string using the default FormattingConfig.

Example

let kserd = Kserd::with_id("AStruct", Value::new_cntr(vec![
    ("a", Kserd::new_num(1_010_101)),
    ("b", Kserd::new_num(3.14)),
    ("c", Kserd::new_str("Hello, world!")),
    ("d", Kserd::new_barrv(vec![100,150,200,225]))
]).unwrap()).unwrap();

let s = kserd.as_str();
assert_eq!(
    &s,
    r#"AStruct (
    a = 1010101
    b = 3.14
    c = "Hello, world!"
    d = b91'"!Mo4'
)"#);

pub fn as_str_with_config(&self, config: FormattingConfig) -> String

Format the Kserd as a string using the specified FormattingConfig.

Example

use kserd::fmt::FormattingConfig;

let kserd = Kserd::with_id("AStruct", Value::new_cntr(vec![
    ("a", Kserd::new_num(1_010_101)),
    ("b", Kserd::new_num(3.14)),
    ("c", Kserd::new_str("Hello, world!")),
    ("d", Kserd::new_barrv(vec![100,150,200,225]))
]).unwrap()).unwrap();

let config = FormattingConfig {
    id_on_containers: false, // don't give container name
    width_limit: None, // all inline
    ..Default::default()
};

let s = kserd.as_str_with_config(config);
assert_eq!(
    &s,
    r#"(a = 1010101, b = 3.14, c = "Hello, world!", d = b91'"!Mo4')"#
);

Methods from Deref<Target = Value<'a>>

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

pub fn tuple(&self) -> Option<&Vec<Kserd<'a>>>

Value is a tuple.

Example

let value = Value::Tuple(vec![Kserd::new_num(101)]);
assert_eq!(value.tuple(), Some(&vec![Kserd::new_num(101)]));

pub fn tuple_mut(&mut self) -> Option<&mut Vec<Kserd<'a>>>

Value is a tuple. Can be altered.

Example

let mut value = Value::Tuple(vec![Kserd::new_num(101)]);
value.tuple_mut().map(|x| x.push(Kserd::new_str("Hello")));
assert_eq!(
    value.tuple(),
    Some(&vec![Kserd::new_num(101), Kserd::new_str("Hello")])
);

pub fn cntr(&self) -> Option<Accessor<&BTreeMap<Kstr<'a>, Kserd<'a>>>>

Value is a container.

Returns an Accessor into the fields, which has utility methods for accessing the fields.

Example

let value = Value::new_cntr(vec![("a", Kserd::new_num(101))]).unwrap();
let accessor = value.cntr().unwrap();
assert_eq!(accessor.get_num("a"), Some(101.into()));

pub fn cntr_mut(
    &mut self
) -> Option<Accessor<&mut BTreeMap<Kstr<'a>, Kserd<'a>>>>

Value is a container. Can be altered.

Returns an Accessor into the fields, which has utility methods for accessing the fields.

Example

let mut value = Value::new_cntr(vec![("a", Kserd::new_num(101))]).unwrap();
let mut accessor = value.cntr_mut().unwrap();
accessor.get_num_mut("a").map(|x| *x = 1.into());
assert_eq!(value, Value::new_cntr(vec![("a", Kserd::new_num(1))]).unwrap());

pub fn seq(&self) -> Option<&Vec<Kserd<'a>>>

Value is a sequence.

Example

let value = Value::Seq(vec![Kserd::new_num(101)]);
assert_eq!(value.seq(), Some(&vec![Kserd::new_num(101)]));

pub fn seq_mut(&mut self) -> Option<&mut Vec<Kserd<'a>>>

Value is a sequence. Can be altered.

Example

let mut value = Value::Seq(vec![Kserd::new_num(101)]);
value.seq_mut().map(|x| x.push(Kserd::new_str("Hello")));
assert_eq!(
    value.seq(),
    Some(&vec![Kserd::new_num(101), Kserd::new_str("Hello")])
);

pub fn tuple_or_seq(&self) -> Option<&Vec<Kserd<'a>>>

Value is a tuple or a sequence.

As tuple and sequence share the same backing store, testing for either can be useful.

Example

let value = Value::Seq(vec![Kserd::new_num(101)]);
assert_eq!(value.tuple_or_seq(), Some(&vec![Kserd::new_num(101)]));

pub fn tuple_or_seq_mut(&mut self) -> Option<&mut Vec<Kserd<'a>>>

Value is a tuple or a sequence. Can be altered.

As tuple and sequence share the same backing store, testing for either can be useful.

Example

let mut value = Value::Tuple(vec![Kserd::new_num(101)]);
value.tuple_or_seq_mut().map(|x| x.push(Kserd::new_str("Hello")));
assert_eq!(
    value.tuple_or_seq(),
    Some(&vec![Kserd::new_num(101), Kserd::new_str("Hello")])
);

pub fn map(&self) -> Option<&BTreeMap<Kserd<'a>, Kserd<'a>>>

Value is a map.

Example

let value = Value::new_map(vec![(
    Kserd::new_str("a"),
    Kserd::new_num(3.14)
)]);
let num = value.map().and_then(|map| {
    map.get(&Kserd::new_str("a"))
});
assert_eq!(num, Some(&Kserd::new_num(3.14)));

pub fn map_mut(&mut self) -> Option<&mut BTreeMap<Kserd<'a>, Kserd<'a>>>

Value is a map. Can be altered.

Example

let mut value = Value::new_map(vec![(
    Kserd::new_str("a"),
    Kserd::new_num(3.14)
)]);

value.map_mut().and_then(|map| {
    map.get_mut(&Kserd::new_str("a"))
}).map(|x| *x = Kserd::new_str("Hello"));

let expect = Value::new_map(vec![(
    Kserd::new_str("a"),
    Kserd::new_str("Hello")
)]);

assert_eq!(value, expect);

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 Kserd<'a>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Kserd<'a>

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

Formats the value using the given formatter.

impl<'a> Deref for Kserd<'a>

type Target = Value<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Value<'a>

Dereferences the value.

impl<'a> DerefMut for Kserd<'a>

fn deref_mut(&mut self) -> &mut Value<'a>

Mutably dereferences the value.

impl<'a> Display for Kserd<'a>

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

Formats the value using the given formatter.

impl<'a> Eq for Kserd<'a>

impl<'a> Ord for Kserd<'a>

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'a> PartialEq<Kserd<'a>> for Kserd<'a>

fn eq(&self, other: &Kserd<'_>) -> bool

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialOrd<Kserd<'a>> for Kserd<'a>

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

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

impl<'a> ToKserd<'a> for Kserd<'a>

fn into_kserd(self) -> Result<Kserd<'a>, ToKserdErr>

Consume the object and convert it into a Kserd data object.