Struct sval::stream::stack::Stack

pub struct Stack { /* fields omitted */ }

A container for the stream state.

Implementations of the Stream trait are encouraged to use a stack for validating their input.

The stack is stateful, and keeps track of open maps and sequences.

Validation

A stack uses its state to validate the structure given to a stream and as a way for a flat, stateless stream to know what it's currently looking at. The stack enforces:

• Only a single root primitive, map or sequence is received.
• Map keys and values are only received within a map.
• Map keys are always received before map values, and every key has a corresponding value.
• Sequence elements are only received within a sequence.
• Every map and sequence is ended, and in the right order.
• Every map key, map value, and sequence element is followed by valid data.

Depth

By default, stacks have a fixed depth (currently ~16, but this may change) so they can work in no-std environments. Each call to map_begin or seq_begin will increase the current depth. If this depth is exceeded then calls to map_begin or seq_begin will fail.

The fixed-depth limit can be removed by adding the arbitrary-depth feature to your Cargo.toml (this also requires the standard library):

[dependencies.sval]
features = ["arbitrary-depth"]

Methods

impl Stack

pub fn new() -> Self

Create a new stack.

pub fn clear(&mut self)

Clear the stack so that it can be re-used.

Any state it currently contains will be lost.

pub fn current(&self) -> Pos

Get the current position in the stack.

pub fn primitive(&mut self) -> Result<Pos, Error>

Push a primitive.

A primitive is a simple value that isn't a map or sequence. That includes:

• Arguments
• u64, i64, u128, i128
• f64
• bool
• char, &str
• Option<T>.

pub fn map_begin(&mut self) -> Result<Pos, Error>

Begin a new map.

The map must be completed by calling map_end.

pub fn map_key(&mut self) -> Result<Pos, Error>

Begin a map key.

The key will be implicitly completed by the value that follows it.

pub fn map_value(&mut self) -> Result<Pos, Error>

Begin a map value.

The value will be implicitly completed by the value that follows it.

pub fn map_end(&mut self) -> Result<Pos, Error>

Complete the current map.

pub fn seq_begin(&mut self) -> Result<Pos, Error>

Begin a new sequence.

the sequence must be completed by calling seq_end.

pub fn seq_elem(&mut self) -> Result<Pos, Error>

Begin a sequence element.

The element will be implicitly completed by the value that follows it.

pub fn seq_end(&mut self) -> Result<Pos, Error>

Complete the current sequence.

pub fn can_end(&self) -> bool

Whether or not the stack has seen a complete and valid stream.

pub fn end(&mut self) -> Result<(), Error>

Complete the stack.

This stack may be re-used after being completed by calling begin.

Trait Implementations

impl Clone for Stack

fn clone(&self) -> Stack

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Stack

fn default() -> Self

Returns the "default value" for a type.