Module preserves::value

Representing, reading, and writing Preserves Values as Rust data

use preserves::value::{IOValue, text, packed};
let v: IOValue = text::iovalue_from_str("<hi>")?;
let w: IOValue = packed::iovalue_from_bytes(b"\xb4\xb3\x02hi\x84")?;
assert_eq!(v, w);
assert_eq!(text::TextWriter::encode_iovalue(&v)?, "<hi>");
assert_eq!(packed::PackedWriter::encode_iovalue(&v)?, b"\xb4\xb3\x02hi\x84");

Preserves Values are categorized in the following way. The core representation type, crate::value::repr::Value, reflects this structure. However, most of the time you will work with IOValue or some other implementation of trait NestedValue, which augments an underlying Value with annotations (e.g. comments) and fixes a strategy for memory management.

                      Value = Atom
                            | Compound
                            | Embedded

                       Atom = Boolean
                            | Double
                            | SignedInteger
                            | String
                            | ByteString
                            | Symbol

                   Compound = Record
                            | Sequence
                            | Set
                            | Dictionary

Memory management

Each implementation of NestedValue chooses a different point in the space of possible approaches to memory management for Values.

IOValue

The most commonly-used and versatile implementation, IOValue, uses std::sync::Arc for internal links in compound Values. Unlike many of the other implementations of NestedValue, IOValue doesn’t offer flexibility in the Rust data type to be used for Preserves embedded values: instead, embedded values in an IOValue are themselves IOValues.

ArcValue<D>, RcValue<D>, and PlainValue<D>

For control over the Rust type to use for embedded values, choose ArcValue, RcValue, or PlainValue. Use ArcValue when you wish to transfer values among threads. RcValue is more niche; it may be useful for complex terms that do not need to cross thread boundaries. PlainValue is even more niche: it does not use a reference-counted pointer type, meaning it does not offer any kind of aliasing or sharing among subterms at all.

Parsing, pretty-printing, encoding and decoding Values

Modules reader and writer supply generic Reader and Writer traits for parsing and unparsing Preserves data. Implementations of Reader and Writer connect Preserves data to specific transfer syntaxes:

• module packed supplies tools for working with the machine-oriented binary syntax
• module text supplies tools for working with human-readable text syntax

Re-exports

• pub use de::from_value;
• pub use de::Deserializer;
• pub use domain::DebugDomainEncode;
• pub use domain::DomainDecode;
• pub use domain::DomainEncode;
• pub use domain::DomainParse;
• pub use domain::FromStrDomainParse;
• pub use domain::IOValueDomainCodec;
• pub use domain::NoEmbeddedDomainCodec;
• pub use domain::ViaCodec;
• pub use merge::merge;
• pub use packed::PackedReader;
• pub use packed::PackedWriter;
• pub use reader::BinarySource;
• pub use reader::BytesBinarySource;
• pub use reader::ConfiguredReader;
• pub use reader::IOBinarySource;
• pub use reader::Reader;
• pub use reader::Token;
• pub use repr::AnnotatedValue;
• pub use repr::ArcValue;
• pub use repr::AtomClass;
• pub use repr::CompoundClass;
• pub use repr::Domain;
• pub use repr::Double;
• pub use repr::DummyValue;
• pub use repr::Embeddable;
• pub use repr::IOValue;
• pub use repr::NestedValue;
• pub use repr::PlainValue;
• pub use repr::RcValue;
• pub use repr::Record;
• pub use repr::UnwrappedIOValue;
• pub use repr::Value;
• pub use repr::ValueClass;
• pub use ser::to_value;
• pub use ser::Serializer;
• pub use text::TextReader;
• pub use text::ToplevelWhitespaceMode;
• pub use text::TextWriter;
• pub use writer::Writer;

Modules

• de
  Support Serde deserialization of Rust data types from Preserves values (not syntax).
• domain
  Traits for working with Preserves embedded values.
• merge
  Implements the Preserves merge of values.
• packed
  Implements the Preserves machine-oriented binary syntax.
• reader
  Generic Reader trait for parsing Preserves Values, implemented by code that provides each specific transfer syntax.
• repr
  In-memory representation of Preserves Values.
• ser
  Support for Serde serialization of Rust data types into Preserves values (not syntax).
• signed_integer
  Representation of Preserves SignedIntegers as i128/u128 (if they fit) or BigInt (if they don’t).
• text
  Implements the Preserves human-oriented text syntax.
• writer
  Generic Writer trait for unparsing Preserves Values, implemented by code that provides each specific transfer syntax.

Structs

• Map
  An ordered map based on a B-Tree.
• Set
  An ordered set based on a B-Tree.