Crate sval

Structured, streaming values.

sval is a serialization framework that treats data as a flat stream of tokens. The source of that data could be some Rust object or parsed from some encoding. It’s well suited to self-describing, text-based formats like JSON.

A note on docs

Even though this library’s API is stable, these docs themselves are still a work-in-progress.

Getting started

Add sval to your Cargo.toml:

[dependencies.sval]
version = "2.13.0"

By default, sval doesn’t depend on Rust’s standard library or integrate with its collection types. To include them, add the alloc or std features:

[dependencies.sval]
version = "2.13.0"
features = ["std"]

The Value trait

Value is a trait for data types to implement that surfaces their structure through visitors called streams. Value is like serde’s Serialize. It can also be used like serde’s Deserialize.

Many standard types in Rust implement the Value trait. It can be derived on your own types using the sval_derive library.

The Stream trait

Stream is a trait for data formats and visitors to implement that observes the structure of values. Stream is like serde’s Serializer. It can also be used like serde’s Deserializer.

Data-model

sval’s data-model is defined by the Stream trait. It includes:

• Null
• Booleans (true, false)
• Text blobs
• Binary blobs
• Integers (u8-u128, i8-i128)
• Binary floating points (f32-f64)
• Maps
• Sequences
• Records
• Tuples
• Enums
• Tags

Tags

Tag is a type for extending sval’s data-model with new kinds of values. Rust’s own () and Option<T> types are expressed as tags. Other examples of tags include text that encodes RFC3339 timestamps or RFC4122 UUIDs.

The tags module contains built-in tags. Other libraries may define their own tags too.

Buffering

Complex or arbitrarily-sized values like strings, maps, and sequences can all be streamed as chunks across multiple calls to avoid intermediate buffering when it’s not necessary.

Object safety

The Value and Stream traits aren’t object-safe themselves, but object-safe wrappers are provided by the sval_dynamic crate. This wrapper works in no-std.

Modules

• default_stream
  Default method implementations for Streams.
• default_value
  Default method implementations for Values.
• tags
  Built-in tags for fundamental types.

Structs

• BinaryArray
  An adapter that streams a slice of 8bit unsigned integers as binary with a fixed size.
• BinarySlice
  An adapter that streams a slice of 8bit unsigned integers as binary.
• Display
  Adapt a fmt::Display into an [sval::Value].
• Error
  An error encountered while streaming a value.
• Index
  The index of a value in its parent context.
• Label
  A textual label for some value.
• MapSlice
  An adapter that streams a slice of key-value pairs as a map.
• Null
  The absence of any meaningful value.
• Tag
  A type tag for a value.

Traits

• Stream
  A consumer of structured data.
• Value
  A producer of structured data.

Functions

• error
  A streaming result with a generic failure.
• stream
  Stream a value through a stream.
• stream_computed
  Stream a value through a stream with an arbitrarily short lifetime.
• stream_display
  Stream a fmt::Display as text into a Stream.
• stream_display_fragments
  Stream a fmt::Display as text fragments into a Stream, without calling Stream::text_begin or Stream::text_end.
• stream_number
  Stream an arbitrary precision number conforming to tags::NUMBER using its fmt::Display implementation.

Type Aliases

• Result
  A generic streaming result.