1//! Structured values.
2//!
3//! This crate contains the [`ValueBag`] type, a container for an anonymous structured value.
4//! `ValueBag`s can be captured in various ways and then formatted, inspected, and serialized
5//! without losing their original structure.
6//!
7//! The producer of a [`ValueBag`] may use a different strategy for capturing than the eventual
8//! consumer. They don't need to coordinate directly.
9
10#![doc(html_root_url = "https://docs.rs/value-bag/1.11.1")]
11#![no_std]
12#![allow(
13 clippy::unnecessary_fallible_conversions,
14 clippy::explicit_auto_deref,
15 clippy::wrong_self_convention
16)]
17
18/*
19# Crate design
20
21This library internally ties several frameworks together. The details of how
22this is done are hidden from end-users. It looks roughly like this:
23
24 ┌─────┐ ┌──────┐
25 │sval2│ │serde1│ 1. libs on crates.io
26 └──┬──┘ └─┬─┬──┘
27 ├──────────┘ │
28 ┌───────▼──┐ ┌───▼───────┐
29 │meta/sval2│ │meta/serde1│ 2. meta crates with features
30 └───────┬──┘ └───┬───────┘
31 │ │
32 ┌─────────────▼──┐ ┌───▼─────────────┐
33 │internal/sval/v2◄─────┤internal/serde/v1│ 3. internal modules with `InternalVisitor`
34 └─────────────┬──┘ └───┬─────────────┘
35 │ │
36 ┌──────▼────────┬───▼────────────┐
37 │Internal::Sval2│Internal::Serde1│ 4. variants in `Internal` enum
38 └───────────────┼────────────────┘
39 │
40┌───────────────────────▼────────────────────────┐
41│ValueBag::capture_sval2│ValueBag::capture_serde1│ 5. ctors on `ValueBag`
42└───────────────────────┼────────────────────────┘
43 │
44┌───────────────────────▼───────────────────────────┐
45│impl Value for ValueBag│impl Serialize for ValueBag│ 6. trait impls on `ValueBag`
46└───────────────────────┴───────────────────────────┘
47
48## 1. libs on crates.io
49
50These are the frameworks like `serde` or `sval`.
51
52## 2. meta crates with features
53
54These are crates that are internal to `value-bag`. They depend on the public
55framework and any utility crates that come along with it. They also expose
56features for any other framework. This is done this way so `value-bag` can use
57Cargo's `crate?/feature` syntax to conditionally add framework support.
58
59## 3. internal modules with `InternalVisitor`
60
61These are modules in `value-bag` that integrate the framework using the
62`InternalVisitor` trait. This makes it possible for that framework to cast
63primitive values and pass-through any other framework.
64
65## 4. variants in `Internal` enum
66
67These are individual variants on the `Internal` enum that the `ValueBag`
68type wraps. Each framework has one or more variants in this enum.
69
70## 5. ctors on `ValueBag`
71
72These are constructors for producers of `ValueBag`s that accept a value
73implementing a serialization trait from a specific framework, like
74`serde::Serialize` or `sval::Value`.
75
76## 7. trait impls on `ValueBag`
77
78These are trait impls for consumers of `ValueBag`s that serialize the
79underlying value, bridging it if it was produced for a different framework.
80*/
81
82#[cfg(any(feature = "std", test))]
83#[macro_use]
84#[allow(unused_imports)]
85extern crate std;
86
87#[cfg(all(not(test), feature = "alloc", not(feature = "std")))]
88#[macro_use]
89#[allow(unused_imports)]
90extern crate core;
91
92#[cfg(all(not(test), feature = "alloc", not(feature = "std")))]
93#[macro_use]
94#[allow(unused_imports)]
95extern crate alloc;
96
97#[cfg(all(not(test), feature = "alloc", not(feature = "std")))]
98#[allow(unused_imports)]
99mod std {
100 pub use crate::{
101 alloc::{borrow, boxed, string, vec},
102 core::*,
103 };
104
105 #[cfg(feature = "owned")]
106 pub use crate::alloc::sync;
107}
108
109#[cfg(not(any(feature = "alloc", feature = "std", test)))]
110#[macro_use]
111#[allow(unused_imports)]
112extern crate core as std;
113
114mod error;
115pub mod fill;
116mod impls;
117mod internal;
118pub mod visit;
119
120#[cfg(any(test, feature = "test"))]
121pub mod test;
122
123#[cfg(feature = "owned")]
124mod owned;
125#[cfg(feature = "owned")]
126pub use self::owned::*;
127
128pub use self::error::Error;
129
130/// A dynamic structured value.
131///
132/// # Capturing values
133///
134/// There are a few ways to capture a value:
135///
136/// - Using the `ValueBag::capture_*` and `ValueBag::from_*` methods.
137/// - Using the standard `From` trait.
138/// - Using the `Fill` API.
139///
140/// ## Using the `ValueBag::capture_*` methods
141///
142/// `ValueBag` offers a few constructor methods that capture values of different kinds.
143/// These methods require a `T: 'static` to support downcasting.
144///
145/// ```
146/// use value_bag::ValueBag;
147///
148/// let value = ValueBag::capture_debug(&42i32);
149///
150/// assert_eq!(Some(42), value.to_i64());
151/// ```
152///
153/// Capturing a value using these methods will retain type information so that
154/// the contents of the bag can be serialized using an appropriate type.
155///
156/// For cases where the `'static` bound can't be satisfied, there's also a few
157/// constructors that exclude it.
158///
159/// ```
160/// # use std::fmt::Debug;
161/// use value_bag::ValueBag;
162///
163/// let value = ValueBag::from_debug(&42i32);
164///
165/// assert_eq!(None, value.to_i64());
166/// ```
167///
168/// These `ValueBag::from_*` methods are lossy though and `ValueBag::capture_*` should be preferred.
169///
170/// ## Using the standard `From` trait
171///
172/// Primitive types can be converted into a `ValueBag` using the standard `From` trait.
173///
174/// ```
175/// use value_bag::ValueBag;
176///
177/// let value = ValueBag::from(42i32);
178///
179/// assert_eq!(Some(42), value.to_i64());
180/// ```
181///
182/// ## Using the `Fill` API
183///
184/// The [`fill`] module provides a way to bridge APIs that may not be directly
185/// compatible with other constructor methods.
186///
187/// The `Fill` trait is automatically implemented for closures, so can usually
188/// be used in libraries that can't implement the trait themselves.
189///
190/// ```
191/// use value_bag::{ValueBag, fill::Slot};
192///
193/// let value = ValueBag::from_fill(&|slot: Slot| {
194/// #[derive(Debug)]
195/// struct MyShortLivedValue;
196///
197/// slot.fill_debug(&MyShortLivedValue)
198/// });
199///
200/// assert_eq!("MyShortLivedValue", format!("{:?}", value));
201/// ```
202///
203/// The trait can also be implemented manually:
204///
205/// ```
206/// # use std::fmt::Debug;
207/// use value_bag::{ValueBag, Error, fill::{Slot, Fill}};
208///
209/// struct FillDebug;
210///
211/// impl Fill for FillDebug {
212/// fn fill(&self, slot: Slot) -> Result<(), Error> {
213/// slot.fill_debug(&42i32 as &dyn Debug)
214/// }
215/// }
216///
217/// let value = ValueBag::from_fill(&FillDebug);
218///
219/// assert_eq!(None, value.to_i64());
220/// ```
221///
222/// # Inspecting values
223///
224/// Once you have a `ValueBag` there are also a few ways to inspect it:
225///
226/// - Using `std::fmt`
227/// - Using `sval`
228/// - Using `serde`
229/// - Using the `ValueBag::visit` method.
230/// - Using the `ValueBag::to_*` methods.
231/// - Using the `ValueBag::downcast_ref` method.
232///
233/// ## Using the `ValueBag::visit` method
234///
235/// The [`visit`] module provides a simple visitor API that can be used to inspect
236/// the structure of primitives stored in a `ValueBag`.
237/// More complex datatypes can then be handled using `std::fmt`, `sval`, or `serde`.
238///
239/// ```
240/// #[cfg(not(feature = "std"))] fn main() {}
241/// #[cfg(feature = "std")]
242/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
243/// # fn escape(buf: &[u8]) -> &[u8] { buf }
244/// # fn itoa_fmt<T>(num: T) -> Vec<u8> { vec![] }
245/// # fn ryu_fmt<T>(num: T) -> Vec<u8> { vec![] }
246/// # use std::io::Write;
247/// use value_bag::{ValueBag, Error, visit::Visit};
248///
249/// // Implement some simple custom serialization
250/// struct MyVisit(Vec<u8>);
251/// impl<'v> Visit<'v> for MyVisit {
252/// fn visit_any(&mut self, v: ValueBag) -> Result<(), Error> {
253/// // Fallback to `Debug` if we didn't visit the value specially
254/// write!(&mut self.0, "{:?}", v).map_err(|_| Error::msg("failed to write value"))
255/// }
256///
257/// fn visit_u64(&mut self, v: u64) -> Result<(), Error> {
258/// self.0.extend_from_slice(itoa_fmt(v).as_slice());
259/// Ok(())
260/// }
261///
262/// fn visit_i64(&mut self, v: i64) -> Result<(), Error> {
263/// self.0.extend_from_slice(itoa_fmt(v).as_slice());
264/// Ok(())
265/// }
266///
267/// fn visit_f64(&mut self, v: f64) -> Result<(), Error> {
268/// self.0.extend_from_slice(ryu_fmt(v).as_slice());
269/// Ok(())
270/// }
271///
272/// fn visit_str(&mut self, v: &str) -> Result<(), Error> {
273/// self.0.push(b'\"');
274/// self.0.extend_from_slice(escape(v.as_bytes()));
275/// self.0.push(b'\"');
276/// Ok(())
277/// }
278///
279/// fn visit_bool(&mut self, v: bool) -> Result<(), Error> {
280/// self.0.extend_from_slice(if v { b"true" } else { b"false" });
281/// Ok(())
282/// }
283/// }
284///
285/// let value = ValueBag::from(42i64);
286///
287/// let mut visitor = MyVisit(vec![]);
288/// value.visit(&mut visitor)?;
289/// # Ok(())
290/// # }
291/// ```
292///
293/// ## Using `std::fmt`
294///
295/// Any `ValueBag` can be formatted using the `std::fmt` machinery as either `Debug`
296/// or `Display`.
297///
298/// ```
299/// use value_bag::ValueBag;
300///
301/// let value = ValueBag::from(true);
302///
303/// assert_eq!("true", format!("{:?}", value));
304/// ```
305///
306/// ## Using `sval`
307///
308/// When the `sval2` feature is enabled, any `ValueBag` can be serialized using `sval`.
309/// This makes it possible to visit any typed structure captured in the `ValueBag`,
310/// including complex datatypes like maps and sequences.
311///
312/// `sval` doesn't need to allocate so can be used in no-std environments.
313///
314/// First, enable the `sval2` feature in your `Cargo.toml`:
315///
316/// ```toml
317/// [dependencies.value-bag]
318/// features = ["sval2"]
319/// ```
320///
321/// Then stream the contents of the `ValueBag` using `sval`.
322///
323/// ```
324/// # #[cfg(not(all(feature = "std", feature = "sval2")))] fn main() {}
325/// # #[cfg(all(feature = "std", feature = "sval2"))]
326/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
327/// # use value_bag_sval2::json as sval_json;
328/// use value_bag::ValueBag;
329///
330/// let value = ValueBag::from(42i64);
331/// let json = sval_json::stream_to_string(value)?;
332/// # Ok(())
333/// # }
334/// ```
335///
336/// ## Using `serde`
337///
338/// When the `serde1` feature is enabled, any `ValueBag` can be serialized using `serde`.
339/// This makes it possible to visit any typed structure captured in the `ValueBag`,
340/// including complex datatypes like maps and sequences.
341///
342/// `serde` needs a few temporary allocations, so also brings in the `std` feature.
343///
344/// First, enable the `serde1` feature in your `Cargo.toml`:
345///
346/// ```toml
347/// [dependencies.value-bag]
348/// features = ["serde1"]
349/// ```
350///
351/// Then stream the contents of the `ValueBag` using `serde`.
352///
353/// ```
354/// # #[cfg(not(all(feature = "std", feature = "serde1")))] fn main() {}
355/// # #[cfg(all(feature = "std", feature = "serde1"))]
356/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
357/// # use value_bag_serde1::json as serde_json;
358/// use value_bag::ValueBag;
359///
360/// let value = ValueBag::from(42i64);
361/// let json = serde_json::to_string(&value)?;
362/// # Ok(())
363/// # }
364/// ```
365///
366/// Also see [`serde.rs`](https://serde.rs) for more examples of writing your own serializers.
367///
368/// ## Using the `ValueBag::to_*` methods
369///
370/// `ValueBag` provides a set of methods for attempting to pull a concrete value out.
371/// These are useful for ad-hoc analysis but aren't intended for exhaustively serializing
372/// the contents of a `ValueBag`.
373///
374/// ```
375/// use value_bag::ValueBag;
376///
377/// let value = ValueBag::capture_display(&42u64);
378///
379/// assert_eq!(Some(42u64), value.to_u64());
380/// ```
381///
382/// ## Using the `ValueBag::downcast_ref` method
383///
384/// When a `ValueBag` is created using one of the `capture_*` constructors, it can be downcast
385/// back to its original value.
386/// This can also be useful for ad-hoc analysis where there's a common possible non-primitive
387/// type that could be captured.
388///
389/// ```
390/// # #[derive(Debug)] struct SystemTime;
391/// # fn now() -> SystemTime { SystemTime }
392/// use value_bag::ValueBag;
393///
394/// let timestamp = now();
395/// let value = ValueBag::capture_debug(&timestamp);
396///
397/// assert!(value.downcast_ref::<SystemTime>().is_some());
398/// ```
399///
400/// # Working with sequences
401///
402/// The `seq` feature of `value-bag` enables utilities for working with values that are sequences.
403/// First, enable the `seq` feature in your `Cargo.toml`:
404///
405/// ```toml
406/// [dependencies.value-bag]
407/// features = ["seq"]
408/// ```
409///
410/// Slices and arrays can be captured as sequences:
411///
412/// ```
413/// # #[cfg(not(all(feature = "serde1", feature = "seq")))] fn main() {}
414/// # #[cfg(all(feature = "serde1", feature = "seq"))]
415/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
416/// # use value_bag_serde1::json as serde_json;
417/// use value_bag::ValueBag;
418///
419/// let value = ValueBag::from_seq_slice(&[1, 2, 3]);
420///
421/// assert_eq!("[1,2,3]", serde_json::to_string(&value)?);
422/// # Ok(())
423/// # }
424/// ```
425///
426/// A sequence captured with either `sval` or `serde` can have its elements extracted:
427///
428/// ```
429/// # #[cfg(not(all(feature = "serde1", feature = "seq")))] fn main() {}
430/// # #[cfg(all(feature = "serde1", feature = "seq"))]
431/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
432/// use value_bag::ValueBag;
433///
434/// let value = ValueBag::from_serde1(&[1.0, 2.0, 3.0]);
435///
436/// let seq = value.to_f64_seq::<Vec<Option<f64>>>().ok_or("not a sequence")?;
437///
438/// assert_eq!(vec![Some(1.0), Some(2.0), Some(3.0)], seq);
439/// # Ok(())
440/// # }
441/// ```
442#[derive(Clone)]
443pub struct ValueBag<'v> {
444 inner: internal::Internal<'v>,
445}
446
447impl<'v> ValueBag<'v> {
448 /// Get an empty `ValueBag`.
449 #[inline]
450 pub const fn empty() -> ValueBag<'v> {
451 ValueBag {
452 inner: internal::Internal::None,
453 }
454 }
455
456 /// Get a `ValueBag` from an `Option`.
457 ///
458 /// This method will return `ValueBag::empty` if the value is `None`.
459 #[inline]
460 pub fn from_option(v: Option<impl Into<ValueBag<'v>>>) -> ValueBag<'v> {
461 match v {
462 Some(v) => v.into(),
463 None => ValueBag::empty(),
464 }
465 }
466
467 /// Get a `ValueBag` from a `u8`.
468 #[inline]
469 pub const fn from_u8(v: u8) -> ValueBag<'v> {
470 ValueBag {
471 inner: internal::Internal::Unsigned(v as u64),
472 }
473 }
474
475 /// Get a `ValueBag` from a `u16`.
476 #[inline]
477 pub const fn from_u16(v: u16) -> ValueBag<'v> {
478 ValueBag {
479 inner: internal::Internal::Unsigned(v as u64),
480 }
481 }
482
483 /// Get a `ValueBag` from a `u32`.
484 #[inline]
485 pub const fn from_u32(v: u32) -> ValueBag<'v> {
486 ValueBag {
487 inner: internal::Internal::Unsigned(v as u64),
488 }
489 }
490
491 /// Get a `ValueBag` from a `u64`.
492 #[inline]
493 pub const fn from_u64(v: u64) -> ValueBag<'v> {
494 ValueBag {
495 inner: internal::Internal::Unsigned(v),
496 }
497 }
498
499 /// Get a `ValueBag` from a `usize`.
500 #[inline]
501 pub const fn from_usize(v: usize) -> ValueBag<'v> {
502 ValueBag {
503 inner: internal::Internal::Unsigned(v as u64),
504 }
505 }
506
507 /// Get a `ValueBag` from a `u128`.
508 #[inline]
509 pub const fn from_u128_ref(v: &'v u128) -> ValueBag<'v> {
510 ValueBag {
511 #[cfg(not(feature = "inline-i128"))]
512 inner: internal::Internal::BigUnsigned(v),
513 #[cfg(feature = "inline-i128")]
514 inner: internal::Internal::BigUnsigned(*v),
515 }
516 }
517
518 /// Get a `ValueBag` from a `u128`.
519 #[inline]
520 #[cfg(feature = "inline-i128")]
521 pub const fn from_u128(v: u128) -> ValueBag<'v> {
522 ValueBag {
523 inner: internal::Internal::BigUnsigned(v),
524 }
525 }
526
527 /// Get a `ValueBag` from a `i8`.
528 #[inline]
529 pub const fn from_i8(v: i8) -> ValueBag<'v> {
530 ValueBag {
531 inner: internal::Internal::Signed(v as i64),
532 }
533 }
534
535 /// Get a `ValueBag` from a `i16`.
536 #[inline]
537 pub const fn from_i16(v: i16) -> ValueBag<'v> {
538 ValueBag {
539 inner: internal::Internal::Signed(v as i64),
540 }
541 }
542
543 /// Get a `ValueBag` from a `i32`.
544 #[inline]
545 pub const fn from_i32(v: i32) -> ValueBag<'v> {
546 ValueBag {
547 inner: internal::Internal::Signed(v as i64),
548 }
549 }
550
551 /// Get a `ValueBag` from a `i64`.
552 #[inline]
553 pub const fn from_i64(v: i64) -> ValueBag<'v> {
554 ValueBag {
555 inner: internal::Internal::Signed(v),
556 }
557 }
558
559 /// Get a `ValueBag` from a `isize`.
560 #[inline]
561 pub const fn from_isize(v: isize) -> ValueBag<'v> {
562 ValueBag {
563 inner: internal::Internal::Signed(v as i64),
564 }
565 }
566
567 /// Get a `ValueBag` from a `i128`.
568 #[inline]
569 pub const fn from_i128_ref(v: &'v i128) -> ValueBag<'v> {
570 ValueBag {
571 #[cfg(not(feature = "inline-i128"))]
572 inner: internal::Internal::BigSigned(v),
573 #[cfg(feature = "inline-i128")]
574 inner: internal::Internal::BigSigned(*v),
575 }
576 }
577
578 /// Get a `ValueBag` from a `i128`.
579 #[inline]
580 #[cfg(feature = "inline-i128")]
581 pub const fn from_i128(v: i128) -> ValueBag<'v> {
582 ValueBag {
583 inner: internal::Internal::BigSigned(v),
584 }
585 }
586
587 /// Get a `ValueBag` from a `f32`.
588 #[inline]
589 pub const fn from_f32(v: f32) -> ValueBag<'v> {
590 ValueBag {
591 inner: internal::Internal::Float(v as f64),
592 }
593 }
594
595 /// Get a `ValueBag` from a `f64`.
596 #[inline]
597 pub const fn from_f64(v: f64) -> ValueBag<'v> {
598 ValueBag {
599 inner: internal::Internal::Float(v),
600 }
601 }
602
603 /// Get a `ValueBag` from a `bool`.
604 #[inline]
605 pub const fn from_bool(v: bool) -> ValueBag<'v> {
606 ValueBag {
607 inner: internal::Internal::Bool(v),
608 }
609 }
610
611 /// Get a `ValueBag` from a `str`.
612 #[inline]
613 pub const fn from_str(v: &'v str) -> ValueBag<'v> {
614 ValueBag {
615 inner: internal::Internal::Str(v),
616 }
617 }
618
619 /// Get a `ValueBag` from a `char`.
620 #[inline]
621 pub const fn from_char(v: char) -> ValueBag<'v> {
622 ValueBag {
623 inner: internal::Internal::Char(v),
624 }
625 }
626
627 /// Get a `ValueBag` from a reference to a `ValueBag`.
628 #[inline]
629 pub const fn by_ref(&self) -> ValueBag<'_> {
630 ValueBag {
631 inner: self.inner.by_ref(),
632 }
633 }
634}
635
636#[cfg(test)]
637mod tests {
638 use super::*;
639 use crate::std::mem;
640
641 #[cfg(feature = "inline-i128")]
642 const SIZE_LIMIT_U64: usize = 4;
643 #[cfg(not(feature = "inline-i128"))]
644 const SIZE_LIMIT_U64: usize = 3;
645
646 #[test]
647 fn value_bag_size() {
648 let size = mem::size_of::<ValueBag<'_>>();
649 let limit = mem::size_of::<u64>() * SIZE_LIMIT_U64;
650
651 if size > limit {
652 panic!(
653 "`ValueBag` size ({} bytes) is too large (expected up to {} bytes)",
654 size, limit,
655 );
656 }
657 }
658}
659