/rust/registry/src/index.crates.io-1949cf8c6b5b557f/sval-2.16.0/src/lib.rs

Source
/*!
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.

# Getting started

For a complete introduction, see [the project readme](https://github.com/sval-rs/sval).

Add `sval` to your `Cargo.toml`:

```toml
[dependencies.sval]
version = "2.16.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` Cargo features:

```toml
[dependencies.sval]
version = "2.16.0"
features = ["std"]
```

`sval` provides procedural macros for deriving its traits.
Add the `derive` Cargo feature to enable them:

```toml
[dependencies.sval]
version = "2.16.0"
features = ["derive"]
```

# 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`)
- Sequences
- Maps
- Tags
- Tagged values
- Records
- Tuples
- Enums

# 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.
*/

#![doc(html_logo_url = "https://raw.githubusercontent.com/sval-rs/sval/main/asset/logo.svg")]
#![no_std]
#![deny(missing_docs)]

#[cfg(feature = "std")]
extern crate std;

#[cfg(all(feature = "alloc", not(feature = "std")))]
extern crate alloc;
#[cfg(all(feature = "alloc", not(feature = "std")))]
extern crate core;

#[cfg(all(feature = "alloc", not(feature = "std")))]
mod std {
    pub use crate::{
        alloc::{borrow, boxed, collections, string, vec},
        core::{cmp, convert, fmt, hash, marker, mem, ops, result, str, write},
    };
}

#[cfg(all(not(feature = "alloc"), not(feature = "std")))]
extern crate core as std;

#[cfg(feature = "derive")]
#[doc(inline)]
pub use sval_derive_macros::*;

mod data;
mod result;
mod stream;
mod value;

#[doc(inline)]
pub use self::{data::*, result::*, stream::*, value::*};

/**
A generic streaming result.
*/
pub type Result<T = (), E = Error> = std::result::Result<T, E>;

/**
Stream a value through a stream.
*/
pub fn stream<'sval>(
    stream: &mut (impl Stream<'sval> + ?Sized),
    value: &'sval (impl Value + ?Sized),
) -> Result {
    stream.value(value)
}

/**
Stream a value through a stream with an arbitrarily short lifetime.
*/
pub fn stream_computed<'sval>(
    stream: &mut (impl Stream<'sval> + ?Sized),
    value: impl Value,
) -> Result {
    stream.value_computed(&value)
}

// NOTE: Tests for implementations of `Value` are in `sval_test`

Coverage Report

Created: 2026-03-17 06:50

Line	Count	Source
1		/*!
2		Structured, streaming values.
3
4		`sval` is a serialization framework that treats data as a flat stream of tokens.
5		The source of that data could be some Rust object or parsed from some encoding.
6		It's well suited to self-describing, text-based formats like JSON.
7
8		# Getting started
9
10		For a complete introduction, see [the project readme](https://github.com/sval-rs/sval).
11
12		Add `sval` to your `Cargo.toml`:
13
14		```toml
15		[dependencies.sval]
16		version = "2.16.0"
17		```
18
19		By default, `sval` doesn't depend on Rust's standard library or integrate with its collection types.
20		To include them, add the `alloc` or `std` Cargo features:
21
22		```toml
23		[dependencies.sval]
24		version = "2.16.0"
25		features = ["std"]
26		```
27
28		`sval` provides procedural macros for deriving its traits.
29		Add the `derive` Cargo feature to enable them:
30
31		```toml
32		[dependencies.sval]
33		version = "2.16.0"
34		features = ["derive"]
35		```
36
37		# The `Value` trait
38
39		[`Value`] is a trait for data types to implement that surfaces their structure through visitors called _streams_.
40		`Value` is like `serde`'s `Serialize`. It can also be used like `serde`'s `Deserialize`.
41
42		Many standard types in Rust implement the `Value` trait. It can be derived on your own types using the `sval_derive` library.
43
44		# The `Stream` trait
45
46		[`Stream`] is a trait for data formats and visitors to implement that observes the structure of _values_.
47		`Stream` is like `serde`'s `Serializer`. It can also be used like `serde`'s `Deserializer`.
48
49		# Data-model
50
51		`sval`'s data-model is defined by the [`Stream`] trait. It includes:
52
53		- Null
54		- Booleans (`true`, `false`)
55		- Text blobs
56		- Binary blobs
57		- Integers (`u8`-`u128`, `i8`-`i128`)
58		- Binary floating points (`f32`-`f64`)
59		- Sequences
60		- Maps
61		- Tags
62		- Tagged values
63		- Records
64		- Tuples
65		- Enums
66
67		# Tags
68
69		[`Tag`] is a type for extending `sval`'s data-model with new kinds of values.
70		Rust's own `()` and `Option<T>` types are expressed as tags.
71		Other examples of tags include text that encodes RFC3339 timestamps or RFC4122 UUIDs.
72
73		The [`tags`] module contains built-in tags.
74		Other libraries may define their own tags too.
75		*/
76
77		#![doc(html_logo_url = "https://raw.githubusercontent.com/sval-rs/sval/main/asset/logo.svg")]
78		#![no_std]
79		#![deny(missing_docs)]
80
81		#[cfg(feature = "std")]
82		extern crate std;
83
84		#[cfg(all(feature = "alloc", not(feature = "std")))]
85		extern crate alloc;
86		#[cfg(all(feature = "alloc", not(feature = "std")))]
87		extern crate core;
88
89		#[cfg(all(feature = "alloc", not(feature = "std")))]
90		mod std {
91		pub use crate::{
92		alloc::{borrow, boxed, collections, string, vec},
93		core::{cmp, convert, fmt, hash, marker, mem, ops, result, str, write},
94		};
95		}
96
97		#[cfg(all(not(feature = "alloc"), not(feature = "std")))]
98		extern crate core as std;
99
100		#[cfg(feature = "derive")]
101		#[doc(inline)]
102		pub use sval_derive_macros::*;
103
104		mod data;
105		mod result;
106		mod stream;
107		mod value;
108
109		#[doc(inline)]
110		pub use self::{data::, result::, stream::, value::};
111
112		/**
113		A generic streaming result.
114		*/
115		pub type Result<T = (), E = Error> = std::result::Result<T, E>;
116
117		/**
118		Stream a value through a stream.
119		*/
120	0	pub fn stream<'sval>(
121	0	stream: &mut (impl Stream<'sval> + ?Sized),
122	0	value: &'sval (impl Value + ?Sized),
123	0	) -> Result {
124	0	stream.value(value)
125	0	} Unexecuted instantiation: sval::stream::<value_bag::internal::sval::v2::VisitorStream, dyn sval_dynamic::value::Value> Unexecuted instantiation: sval::stream::<_, _>
126
127		/**
128		Stream a value through a stream with an arbitrarily short lifetime.
129		*/
130	0	pub fn stream_computed<'sval>(
131	0	stream: &mut (impl Stream<'sval> + ?Sized),
132	0	value: impl Value,
133	0	) -> Result {
134	0	stream.value_computed(&value)
135	0	} Unexecuted instantiation: sval::stream_computed::<sval_buffer::value::ValueBuf, &dyn sval_dynamic::value::Value> Unexecuted instantiation: sval::stream_computed::<value_bag::internal::sval::v2::VisitorStream, &dyn sval_dynamic::value::Value> Unexecuted instantiation: sval::stream_computed::<_, _>
136
137		// NOTE: Tests for implementations of `Value` are in `sval_test`