deser_value/lib.rs
1//! A dynamic value type for deser.
2//!
3//! [`Value`] can hold any value of the deser data model. It's useful for
4//! data whose structure is not known up front, to inspect or transform data
5//! before it's deserialized into a type, or to convert between formats:
6//!
7//! ```
8//! use deser_value::{Value, value};
9//!
10//! let mut config: Value =
11//! deser_json::from_str(r#"{"name": "app", "port": 8080}"#).unwrap();
12//! config["port"] = value!(9090);
13//! config["tags"] = value!(["web", "prod"]);
14//! assert_eq!(
15//! deser_json::to_string(&config).unwrap(),
16//! r#"{"name":"app","port":9090,"tags":["web","prod"]}"#
17//! );
18//! ```
19//!
20//! Values are converted from and into other types with [`to_value`] and
21//! [`from_value`]. To configure the conversion (for instance to add
22//! layers) use the [`Serializer`] and the [`Deserializer`]. Values can be
23//! built with the [`value!`] macro.
24//!
25//! # Retained Information
26//!
27//! Values try to retain as much information as possible, which means that
28//! a value that is deserialized and serialized again comes out the same:
29//!
30//! * Map keys can be any value (like integers in CBOR) and maps retain the
31//! order of their entries.
32//! * Values that extend the data model (like date-times, UUIDs or exact
33//! numbers, see [`deser::ext`](deser_core::ext)) retain their type.
34//! * Maps and sequences retain their [`Order`](deser_core::Order).
35//! * Bytes retain their [fallback](deser_core::Bytes::fallback).
36//! * [Event data](deser_core::State::event), which is information that is
37//! attached to values but not part of the data model (for instance CBOR
38//! tags or formatting hints), is retained in the [`Meta`] data of values.
39//! * If the format tracks locations (see
40//! [`TrackLocations`](deser_core::TrackLocations)), values retain their
41//! [`Span`] in the input. Types that are deserialized from such values
42//! report errors at the original location:
43//!
44//! ```
45//! use deser::{Context, Deserialize, TrackLocations};
46//! use deser_value::{Value, from_value};
47//!
48//! #[derive(Debug, Deserialize)]
49//! struct Config {
50//! port: u16,
51//! }
52//!
53//! let config = deser_json::DeserializerConfig::builder()
54//! .context(Context::with(TrackLocations(true)))
55//! .build();
56//! let value: Value = config.from_str("{\n \"port\": \"80\"\n}").unwrap();
57//! let err = from_value::<Config>(&value).unwrap_err();
58//! assert_eq!((err.line(), err.column()), (Some(2), Some(11)));
59//! ```
60//!
61//! # Duplicate Keys
62//!
63//! Map keys are unique. If a key is given more than once, the
64//! [`DuplicateKeys`](deser_core::de::DuplicateKeys) policy of the
65//! deserialization decides: by default the deserialization fails, otherwise
66//! the first or the last value is used. The keys of multimaps (like the
67//! parameters of query strings) collect their values instead, see
68//! [`Seq::is_repeated`].
69#![doc(html_logo_url = "https://raw.githubusercontent.com/mitsuhiko/deser/main/artwork/logo.svg")]
70
71mod convert;
72mod de;
73mod index;
74mod macros;
75mod map;
76mod seq;
77mod ser;
78mod tree;
79mod value;
80
81pub use self::convert::{Deserializer, Serializer, from_value, to_value};
82pub use self::index::ValueIndex;
83pub use self::map::{IntoIter, Iter, IterMut, Keys, Map, MapKey, Values, ValuesMut};
84pub use self::seq::Seq;
85pub use self::value::{Kind, Meta, Span, Value};
86
87// values must never prevent data from being shared between threads.
88const _: () = {
89 const fn assert_send_sync<T: Send + Sync>() {}
90 assert_send_sync::<Value>();
91};