Enum Atom 

#[non_exhaustive]
#[repr(C, u64)]
pub enum Atom<'a> {
    Null,
    Bool(bool),
    Str(Text<'a>),
    Lexical(Text<'a>),
    Bytes(Bytes<'a>),
    Char(char),
    U64(u64),
    I64(i64),
    F32(f32),
    F64(f64),
    Ext(ExtValue<'a>),
    Implicit(Implicit<'a>),
}

An atom is a primitive value for serialization and deserialization.

Atoms are values that are sent directly to a serializer or deserializer. Examples for this are booleans or integers. This is in contrast to compound values like maps, structs or sequences.

Atoms are non exhaustive which means that new variants might appear in the future. Deser tries to build around this restriction for instance through the default handling of atoms (default_atom) so that one always has something to call.

Values which are not part of the core data model are represented as Atom::Ext. For more information see ext.

Bytes can carry a representation for formats without native bytes which formats with native bytes ignore.

Floats are F32 or F64 depending on their precision. A single precision float is a value of its own as its shortest text differs from the one of the same value as f64 (0.1f32 is 0.1, as f64 it’s 0.10000000149011612). Sinks that do not care about the precision only need to handle F64: the default handling of atoms widens F32 (see default_atom).

Text whose type the format cannot express is Lexical. It’s a string for everybody who does not care, see there for more information. A value whose type the format inferred from its text is Implicit, it carries the text for types that do not accept the value.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Null

Bool(bool)

Str(Text<'a>)

Lexical(Text<'a>)

The lexical form of a value whose type the format cannot express.

Some formats cannot say what type a piece of text is: everything in a query string is text, and so are the keys of JSON objects. Such text is emitted as a lexical atom and the sink it’s delivered to decides what it means: numbers and booleans parse it, strings take it as it is. Text that is known to be a string (like a string value in JSON, where the number 42 could have been written instead of "42") is Str.

Sinks receive it as Str unless they handle it (see default_atom). Sinks that borrow strings have to handle it themselves, the fallback does not borrow for the lifetime of the input. Serializers write it as string.

Integers and floats parse lexical atoms with str::parse, how booleans are spelled, if empty text is a missing value and if text is a sequence of one element depends on the LexicalRules of the deserialization, which the format sets. All other types that accept strings accept lexical atoms as string.

Bytes(Bytes<'a>)

Char(char)

U64(u64)

I64(i64)

F32(f32)

A single precision float.

Formats write it with the precision of an f32, for instance text formats with the shortest text that reads back as the same f32. Formats do not produce it when they read floats (the precision of a float in the input is unknown or, like in CBOR, an encoding detail). Sinks receive it as F64 unless they handle it (see default_atom).

F64(f64)

A double precision float.

Ext(ExtValue<'a>)

A value that extends the data model.

See ext for more information.

Implicit(Implicit<'a>)

A value whose type the format inferred from its text.

See Implicit for more information.

Implementations

impl<'a> Atom<'a>

pub fn to_static(&self) -> Atom<'static>

Makes a static clone of the atom decoupling the lifetimes.

pub fn as_borrowed(&self) -> Atom<'_>

Returns an atom borrowing from this one.

This is useful to pass a stored atom on without cloning its data.

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

Returns the text of a Str or Lexical atom.

use deser::Atom;

assert_eq!(Atom::Lexical("42".into()).as_str(), Some("42"));
assert_eq!(Atom::Str("42".into()).as_str(), Some("42"));
assert_eq!(Atom::U64(42).as_str(), None);

pub fn name(&self) -> &str

Returns the human readable name of the atom.

pub fn unexpected_error(&self, expectation: &str) -> Error

Creates an “unexpected” error.

This is the error that default_atom returns for atoms it cannot pass on in another form, with what the sink expects. Sinks (and Deserialize::deserialize_atom) should pass the atoms they do not accept to default_atom rather than returning this error, so that extension values are passed on as their fallback and lexical atoms as strings.

use deser::Atom;

let err = Atom::Bool(true).unexpected_error("u32");
assert_eq!(err.message(), "unexpected bool, expected u32");

Trait Implementations

impl<'a> Clone for Atom<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Atom<'a>

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

Formats the value using the given formatter.

impl<'a> From<Atom<'a>> for Event<'a>

fn from(atom: Atom<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Atom<'a>> for Emit<'a>

fn from(atom: Atom<'a>) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for Atom<'a>

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

Equality operator ==.

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

Inequality operator !=.

impl<'a> StructuralPartialEq for Atom<'a>