Trait sval::value::Value

pub trait Value {
    fn stream(&self, stream: &mut Stream<'_>) -> Result;
}

A value with a streamable structure.

Implementing Value

Implementations of Value are expected to conform to the following model:

Only a single primitive, map or sequence is streamed

The following Value is valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        // VALID: The stream can take the primitive
        // value 42
        stream.any(42)
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.any(42)?;

        // INVALID: The stream already received the
        // primitive value 42
        stream.any(43)
    }
}

All maps and sequences are completed, and in the right order

The following Value is valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;
        stream.map_key("a")?;
        stream.map_value_begin()?.seq_begin(None)?;

        // VALID: The sequence is completed, then the map is completed
        stream.seq_end()?;
        stream.map_end()
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;
        stream.map_key("a")?;
        stream.map_value_begin()?.seq_begin(None)?;

        // INVALID: The map is completed before the sequence,
        // even though the sequence was started last.
        stream.map_end()?;
        stream.seq_end()
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;

        // INVALID: The map is never completed
        Ok(())
    }
}

Map keys and values are received before their corresponding structure

The following Value is valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;

        // VALID: The `map_key` and `map_value` methods
        // always call the underlying stream correctly
        stream.map_key("a")?;
        stream.map_value("b")?;

        // VALID: `map_key` and `map_value` are called before
        // their actual values are given
        stream.map_key_begin()?.any("c")?;
        stream.map_value_begin()?.any("d")?;

        stream.map_end()
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;

        // INVALID: The underlying `map_key` and `map_value` methods
        // aren't being called before their actual values are given
        stream.any("a")?;
        stream.any("b")?;

        stream.map_end()
    }
}

Map keys are received before values

The following Value is valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;

        // VALID: The key is streamed before the value
        stream.map_key("a")?;
        stream.map_value("b")?;

        stream.map_end()
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.map_begin(None)?;

        // INVALID: The value is streamed before the key
        stream.map_value("b")?;
        stream.map_key("a")?;

        stream.map_end()
    }
}

Sequence elements are received before their corresponding structure

The following Value is valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.seq_begin(None)?;

        // VALID: The `seq_elem` method
        // always calls the underlying stream correctly
        stream.seq_elem("a")?;

        // VALID: `seq_elem` is called before
        // their actual values are given
        stream.seq_elem_begin()?.any("b")?;

        stream.seq_end()
    }
}

The following Value is not valid:

impl Value for MyValue {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.seq_begin(None)?;

        // INVALID: The underlying `seq_elem` method
        // isn't being called before the actual value is given
        stream.any("a")?;

        stream.seq_end()
    }
}

Required methods

fn stream(&self, stream: &mut Stream<'_>) -> Result

Stream this value.

Examples

Use a stream::OwnedStream to stream a value:

use sval::stream::OwnedStream;

let mut stream = OwnedStream::new(MyStream);
stream.any(42)?;

It's less convenient, but the stream method can be called directly instead of using OwnedStream.any:

use sval::{
    stream::OwnedStream,
    value::Value,
};

let mut stream = OwnedStream::new(MyStream);
42.stream(&mut stream.borrow_mut())?;

Loading content...

Implementations on Foreign Types

impl Value for ()

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T> Value for Option<T> where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T> Value for [T] where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T, U> Value for (T, U) where
    T: Value,
    U: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for u8

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for u16

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for u32

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for u64

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for i8

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for i16

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for i32

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for i64

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for u128

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for i128

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for f32

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for f64

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for bool

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for char

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for str

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<'a> Value for Arguments<'a>

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T: ?Sized> Value for Box<T> where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T: ?Sized> Value for Rc<T> where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for String

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T> Value for Vec<T> where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<K, V> Value for BTreeMap<K, V> where
    K: Eq + Value,
    V: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl Value for dyn Error + 'static

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T: ?Sized> Value for Arc<T> where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<K, V, H> Value for HashMap<K, V, H> where
    K: Hash + Eq + Value,
    V: Value,
    H: BuildHasher, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<'a, T: ?Sized> Value for &'a T where
    T: Value, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

Loading content...

Implementors

impl Value for OwnedValue

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<'a> Value for sval::stream::Arguments<'a>

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<'a> Value for Source<'a>

fn stream(&self, stream: &mut Stream<'_>) -> Result

impl<T> Value for ToValue<T> where
    T: Serialize, 

fn stream(&self, stream: &mut Stream<'_>) -> Result

Loading content...