Struct value_bag::ValueBag

pub struct ValueBag<'v> { /* private fields */ }

A dynamic structured value.

Capturing values

There are a few ways to capture a value:

• Using the ValueBag::capture_* and ValueBag::from_* methods.
• Using the standard From trait.
• Using the Fill API.

Using the ValueBag::capture_* methods

ValueBag offers a few constructor methods that capture values of different kinds. These methods require a T: 'static to support downcasting.

use value_bag::ValueBag;

let value = ValueBag::capture_debug(&42i32);

assert_eq!(Some(42), value.to_i64());

Capturing a value using these methods will retain type information so that the contents of the bag can be serialized using an appropriate type.

For cases where the 'static bound can’t be satisfied, there’s also a few constructors that exclude it.

use value_bag::ValueBag;

let value = ValueBag::from_debug(&42i32);

assert_eq!(None, value.to_i64());

These ValueBag::from_* methods are lossy though and ValueBag::capture_* should be preferred.

Using the standard From trait

Primitive types can be converted into a ValueBag using the standard From trait.

use value_bag::ValueBag;

let value = ValueBag::from(42i32);

assert_eq!(Some(42), value.to_i64());

Using the Fill API

The fill module provides a way to bridge APIs that may not be directly compatible with other constructor methods.

The Fill trait is automatically implemented for closures, so can usually be used in libraries that can’t implement the trait themselves.

use value_bag::{ValueBag, fill::Slot};

let value = ValueBag::from_fill(&|slot: Slot| {
    #[derive(Debug)]
    struct MyShortLivedValue;

    slot.fill_debug(&MyShortLivedValue)
});

assert_eq!("MyShortLivedValue", format!("{:?}", value));

The trait can also be implemented manually:

use value_bag::{ValueBag, Error, fill::{Slot, Fill}};

struct FillDebug;

impl Fill for FillDebug {
    fn fill(&self, slot: Slot) -> Result<(), Error> {
        slot.fill_debug(&42i32 as &dyn Debug)
    }
}

let value = ValueBag::from_fill(&FillDebug);

assert_eq!(None, value.to_i64());

Inspecting values

Once you have a ValueBag there are also a few ways to inspect it:

• Using std::fmt
• Using sval
• Using serde
• Using the ValueBag::visit method.
• Using the ValueBag::to_* methods.
• Using the ValueBag::downcast_ref method.

Using the ValueBag::visit method

The visit module provides a simple visitor API that can be used to inspect the structure of primitives stored in a ValueBag. More complex datatypes can then be handled using std::fmt, sval, or serde.

#[cfg(not(feature = "std"))] fn main() {}
#[cfg(feature = "std")]
use value_bag::{ValueBag, Error, visit::Visit};

// Implement some simple custom serialization
struct MyVisit(Vec<u8>);
impl<'v> Visit<'v> for MyVisit {
    fn visit_any(&mut self, v: ValueBag) -> Result<(), Error> {
        // Fallback to `Debug` if we didn't visit the value specially
        write!(&mut self.0, "{:?}", v).map_err(|_| Error::msg("failed to write value"))
    }

    fn visit_u64(&mut self, v: u64) -> Result<(), Error> {
        self.0.extend_from_slice(itoa_fmt(v).as_slice());
        Ok(())
    }

    fn visit_i64(&mut self, v: i64) -> Result<(), Error> {
        self.0.extend_from_slice(itoa_fmt(v).as_slice());
        Ok(())
    }

    fn visit_f64(&mut self, v: f64) -> Result<(), Error> {
        self.0.extend_from_slice(ryu_fmt(v).as_slice());
        Ok(())
    }

    fn visit_str(&mut self, v: &str) -> Result<(), Error> {
        self.0.push(b'\"');
        self.0.extend_from_slice(escape(v.as_bytes()));
        self.0.push(b'\"');
        Ok(())
    }

    fn visit_bool(&mut self, v: bool) -> Result<(), Error> {
        self.0.extend_from_slice(if v { b"true" } else { b"false" });
        Ok(())
    }
}

let value = ValueBag::from(42i64);

let mut visitor = MyVisit(vec![]);
value.visit(&mut visitor)?;

Using std::fmt

Any ValueBag can be formatted using the std::fmt machinery as either Debug or Display.

use value_bag::ValueBag;

let value = ValueBag::from(true);

assert_eq!("true", format!("{:?}", value));

Using sval

When the sval2 feature is enabled, any ValueBag can be serialized using sval. This makes it possible to visit any typed structure captured in the ValueBag, including complex datatypes like maps and sequences.

sval doesn’t need to allocate so can be used in no-std environments.

First, enable the sval2 feature in your Cargo.toml:

[dependencies.value-bag]
features = ["sval2"]

Then stream the contents of the ValueBag using sval.

use value_bag::ValueBag;

let value = ValueBag::from(42i64);
let json = sval_json::stream_to_string(value)?;

Using serde

When the serde1 feature is enabled, any ValueBag can be serialized using serde. This makes it possible to visit any typed structure captured in the ValueBag, including complex datatypes like maps and sequences.

serde needs a few temporary allocations, so also brings in the std feature.

First, enable the serde1 feature in your Cargo.toml:

[dependencies.value-bag]
features = ["serde1"]

Then stream the contents of the ValueBag using serde.

use value_bag::ValueBag;

let value = ValueBag::from(42i64);
let json = serde_json::to_string(&value)?;

Also see serde.rs for more examples of writing your own serializers.

Using the ValueBag::to_* methods

ValueBag provides a set of methods for attempting to pull a concrete value out. These are useful for ad-hoc analysis but aren’t intended for exhaustively serializing the contents of a ValueBag.

use value_bag::ValueBag;

let value = ValueBag::capture_display(&42u64);

assert_eq!(Some(42u64), value.to_u64());

Using the ValueBag::downcast_ref method

When a ValueBag is created using one of the capture_* constructors, it can be downcast back to its original value. This can also be useful for ad-hoc analysis where there’s a common possible non-primitive type that could be captured.

use value_bag::ValueBag;

let timestamp = now();
let value = ValueBag::capture_debug(&timestamp);

assert!(value.downcast_ref::<SystemTime>().is_some());

Implementations

impl<'v> ValueBag<'v>

pub fn to_str(&self) -> Option<Cow<'v, str>>

Try get a str from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones. If the serialization implementation produces a short lived string it will be allocated.

impl<'v> ValueBag<'v>

pub fn try_capture<T>(value: &'v T) -> Option<Self>where T: ?Sized + 'static,

Try capture a raw value.

This method will return Some if the value is a simple primitive that can be captured without losing its structure. In other cases this method will return None.

pub fn to_u64(&self) -> Option<u64>

Try get a u64 from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_i64(&self) -> Option<i64>

Try get a i64 from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_u128(&self) -> Option<u128>

Try get a u128 from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_i128(&self) -> Option<i128>

Try get a i128 from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_f64(&self) -> Option<f64>

Try get a f64 from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_bool(&self) -> Option<bool>

Try get a bool from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_char(&self) -> Option<char>

Try get a char from this value.

This method is cheap for primitive types, but may call arbitrary serialization implementations for complex ones.

pub fn to_borrowed_str(&self) -> Option<&'v str>

Try get a str from this value.

This method is cheap for primitive types. It won’t allocate an owned String if the value is a complex type.

pub fn is<T: 'static>(&self) -> bool

Check whether this value can be downcast to T.

pub fn downcast_ref<T: 'static>(&self) -> Option<&T>

Try downcast this value to T.

impl<'v> ValueBag<'v>

pub fn capture_error<T>(value: &'v T) -> Selfwhere T: Error + 'static,

Get a value from an error.

pub fn from_dyn_error(value: &'v (dyn Error + 'static)) -> Self

Get a value from an erased value.

pub fn to_borrowed_error(&self) -> Option<&'v (dyn Error + 'static)>

Try get an error from this value.

impl<'v> ValueBag<'v>

pub fn from_fill<T>(value: &'v T) -> Selfwhere T: Fill,

Get a value from a fillable slot.

impl<'v> ValueBag<'v>

pub fn capture_debug<T>(value: &'v T) -> Selfwhere T: Debug + 'static,

Get a value from a debuggable type.

This method will attempt to capture the given value as a well-known primitive before resorting to using its Debug implementation.

pub fn capture_display<T>(value: &'v T) -> Selfwhere T: Display + 'static,

Get a value from a displayable type.

This method will attempt to capture the given value as a well-known primitive before resorting to using its Display implementation.

pub fn from_debug<T>(value: &'v T) -> Selfwhere T: Debug,

Get a value from a debuggable type without capturing support.

pub fn from_display<T>(value: &'v T) -> Selfwhere T: Display,

Get a value from a displayable type without capturing support.

pub fn from_dyn_debug(value: &'v dyn Debug) -> Self

Get a value from a debuggable type without capturing support.

pub fn from_dyn_display(value: &'v dyn Display) -> Self

Get a value from a displayable type without capturing support.

impl<'v> ValueBag<'v>

pub fn capture_serde1<T>(value: &'v T) -> Selfwhere T: Serialize + 'static,

Get a value from a structured type.

This method will attempt to capture the given value as a well-known primitive before resorting to using its Value implementation.

pub fn from_serde1<T>(value: &'v T) -> Selfwhere T: Serialize,

Get a value from a structured type without capturing support.

impl<'v> ValueBag<'v>

pub fn capture_sval2<T>(value: &'v T) -> Selfwhere T: Value + 'static,

Get a value from a structured type.

This method will attempt to capture the given value as a well-known primitive before resorting to using its Value implementation.

pub fn from_sval2<T>(value: &'v T) -> Selfwhere T: Value,

Get a value from a structured type without capturing support.

pub fn from_dyn_sval2(value: &'v dyn Value) -> Self

Get a value from a structured type without capturing support.

impl<'v> ValueBag<'v>

pub fn visit(&self, visitor: impl Visit<'v>) -> Result<(), Error>

Visit this value using a simple visitor.

The visitor isn’t strictly required to inspect the contents of a value bag. It’s useful for simple cases where a full framework like serde or sval isn’t necessary.

impl<'v> ValueBag<'v>

pub fn to_test_token(&self) -> TestToken

Convert the value bag into a token for testing.

This isn’t a general-purpose API for working with values outside of testing.

impl<'v> ValueBag<'v>

pub fn by_ref<'u>(&'u self) -> ValueBag<'u>

Get a ValueBag from a reference to a ValueBag.

Trait Implementations

impl<'v> Clone for ValueBag<'v>

fn clone(&self) -> ValueBag<'v>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'v> Debug for ValueBag<'v>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'v> Display for ValueBag<'v>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, 'v> From<&'a ()> for ValueBag<'v>

fn from(value: &'a ()) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a bool> for ValueBag<'v>

fn from(value: &'a bool) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a char> for ValueBag<'v>

fn from(value: &'a char) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a f32> for ValueBag<'v>

fn from(value: &'a f32) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a f64> for ValueBag<'v>

fn from(value: &'a f64) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a i16> for ValueBag<'v>

fn from(value: &'a i16) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a i32> for ValueBag<'v>

fn from(value: &'a i32) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a i64> for ValueBag<'v>

fn from(value: &'a i64) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a i8> for ValueBag<'v>

fn from(value: &'a i8) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a isize> for ValueBag<'v>

fn from(value: &'a isize) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a u16> for ValueBag<'v>

fn from(value: &'a u16) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a u32> for ValueBag<'v>

fn from(value: &'a u32) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a u64> for ValueBag<'v>

fn from(value: &'a u64) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a u8> for ValueBag<'v>

fn from(value: &'a u8) -> Self

Converts to this type from the input type.

impl<'a, 'v> From<&'a usize> for ValueBag<'v>

fn from(value: &'a usize) -> Self

Converts to this type from the input type.

impl<'v> From<&'v String> for ValueBag<'v>

fn from(v: &'v String) -> ValueBag<'v>

Converts to this type from the input type.

impl<'v> From<&'v i128> for ValueBag<'v>

fn from(value: &'v i128) -> Self

Converts to this type from the input type.

impl<'v> From<&'v str> for ValueBag<'v>

fn from(value: &'v str) -> Self

Converts to this type from the input type.

impl<'v> From<&'v u128> for ValueBag<'v>

fn from(value: &'v u128) -> Self

Converts to this type from the input type.

impl<'v> From<()> for ValueBag<'v>

fn from(value: ()) -> Self

Converts to this type from the input type.

impl<'v> From<bool> for ValueBag<'v>

fn from(value: bool) -> Self

Converts to this type from the input type.

impl<'v> From<char> for ValueBag<'v>

fn from(value: char) -> Self

Converts to this type from the input type.

impl<'v> From<f32> for ValueBag<'v>

fn from(value: f32) -> Self

Converts to this type from the input type.

impl<'v> From<f64> for ValueBag<'v>

fn from(value: f64) -> Self

Converts to this type from the input type.

impl<'v> From<i16> for ValueBag<'v>

fn from(value: i16) -> Self

Converts to this type from the input type.

impl<'v> From<i32> for ValueBag<'v>

fn from(value: i32) -> Self

Converts to this type from the input type.

impl<'v> From<i64> for ValueBag<'v>

fn from(value: i64) -> Self

Converts to this type from the input type.

impl<'v> From<i8> for ValueBag<'v>

fn from(value: i8) -> Self

Converts to this type from the input type.

impl<'v> From<isize> for ValueBag<'v>

fn from(value: isize) -> Self

Converts to this type from the input type.

impl<'v> From<u16> for ValueBag<'v>

fn from(value: u16) -> Self

Converts to this type from the input type.

impl<'v> From<u32> for ValueBag<'v>

fn from(value: u32) -> Self

Converts to this type from the input type.

impl<'v> From<u64> for ValueBag<'v>

fn from(value: u64) -> Self

Converts to this type from the input type.

impl<'v> From<u8> for ValueBag<'v>

fn from(value: u8) -> Self

Converts to this type from the input type.

impl<'v> From<usize> for ValueBag<'v>

fn from(value: usize) -> Self

Converts to this type from the input type.

impl<'v> Serialize for ValueBag<'v>

fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'v> Value for ValueBag<'v>

fn stream<'sval, S: Stream<'sval> + ?Sized>(&'sval self, s: &mut S) -> Result

Stream this value through a [Stream].

fn to_bool(&self) -> Option<bool>

Try convert this value into a boolean.

fn to_f32(&self) -> Option<f32>

Try convert this value into a 32bit binary floating point number.

fn to_f64(&self) -> Option<f64>

Try convert this value into a 64bit binary floating point number.

fn to_i8(&self) -> Option<i8>

Try convert this value into a signed 8bit integer.

fn to_i16(&self) -> Option<i16>

Try convert this value into a signed 16bit integer.

fn to_i32(&self) -> Option<i32>

Try convert this value into a signed 32bit integer.

fn to_i64(&self) -> Option<i64>

Try convert this value into a signed 64bit integer.

fn to_i128(&self) -> Option<i128>

Try convert this value into a signed 128bit integer.

fn to_u8(&self) -> Option<u8>

Try convert this value into an unsigned 8bit integer.

fn to_u16(&self) -> Option<u16>

Try convert this value into an unsigned 16bit integer.

fn to_u32(&self) -> Option<u32>

Try convert this value into an unsigned 32bit integer.

fn to_u64(&self) -> Option<u64>

Try convert this value into an unsigned 64bit integer.

fn to_u128(&self) -> Option<u128>

Try convert this value into an unsigned 128bit integer.

fn to_text(&self) -> Option<&str>

Try convert this value into a text string.

fn to_binary(&self) -> Option<&[u8]>

Try convert this value into a bitstring.

impl<'sval> ValueRef<'sval> for ValueBag<'sval>

fn stream_ref<S: Stream<'sval> + ?Sized>(&self, s: &mut S) -> Result

Stream this value through a [Stream].