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 APIs like unexpected_atom so that one always have 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). Consumers that do not care about the precision can widen it.

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 Sink::unexpected_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 Sink::unexpected_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 widen_float(self) -> Atom<'a>

Widens an F32 into an F64.

Other atoms are returned unchanged. This is useful for consumers which do not distinguish the precision of floats.

use deser::Atom;

assert_eq!(Atom::F32(1.5).widen_float(), Atom::F64(1.5));
assert_eq!(Atom::U64(1).widen_float(), Atom::U64(1));

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 useful when implementing sinks that do not want to deal with an atom of a specific type. The default implementation of a Sink uses this method as follows:

impl<'de> Sink<'de> for MySink {
    fn atom(
        &mut self,
        atom: Atom,
        _state: &mut State,
    ) -> Result<(), Error> {
        Err(atom.unexpected_error(&self.expecting()))
    }
}

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 Chunk<'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>