Struct InputBuffer 

pub struct InputBuffer<D: StreamDeserializer> { /* private fields */ }

Splits a stream into values without doing IO.

The buffer holds the data of a stream that was read so far and splits it into values with a StreamDeserializer. It does not do IO itself which makes it usable with any kind of IO: poll reports if a value is ready or if more input is needed. Input is read into read_buf and committed with filled (or set_eof at the end of the stream). Once a value is ready it’s deserialized with deserialize:

use std::io::Read;
use deser::stream::{InputBuffer, Status};

fn read_all(mut input: impl Read) -> Result<Vec<u64>, deser::Error> {
    // `Lines` is the stream deserializer of a format with a number
    // per line
    let mut buffer = InputBuffer::new(Lines);
    let mut values = Vec::new();
    loop {
        match buffer.poll()? {
            Status::Ready => values.push(buffer.deserialize()?),
            Status::End => return Ok(values),
            Status::NeedInput => match input.read(buffer.read_buf())? {
                0 => buffer.set_eof(),
                read => buffer.filled(read),
            },
        }
    }
}

assert_eq!(read_all(&b"1\n2\n3"[..]).unwrap(), [1, 2, 3]);

The offsets, lines and columns of errors refer to the stream.

Stream deserializers which support it can also deserialize values while their input arrives, see drive_partial.

Implementations

impl<D: StreamDeserializer> InputBuffer<D>

pub fn new(deserializer: D) -> InputBuffer<D>

Creates an empty buffer.

To continue a stream whose context is known (for instance the names of the columns of a CSV file), create the stream deserializer with that context.

The values are deserialized in the context of the deserializer (see StreamDeserializer::context) unless set_context replaces it.

pub fn set_context(&mut self, context: Context)

Sets the context the values are deserialized in.

This replaces the context of the deserializer. The context is given to the drivers the values are deserialized with (see DeserializeDriver::set_default_context): a context the driver has already takes precedence for the types it has a value for.

pub fn context(&self) -> &Context

Returns the context the values are deserialized in.

pub fn deserializer(&self) -> &D

Returns the stream deserializer.

pub fn into_parts(self) -> (D, Vec<u8>)

Returns the stream deserializer and the input that was read but not consumed.

pub fn offset(&self) -> usize

Returns the number of bytes of the stream that were consumed.

This is the offset of the unconsumed input in the stream.

pub fn buffered(&self) -> usize

Returns the number of bytes which were read but not consumed.

pub fn is_eof(&self) -> bool

Returns true if the end of the stream was reached.

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

Checks if the next value is ready.

This invokes the stream deserializer to find the next value if needed. Once the status is Status::Ready, the value has to be deserialized with deserialize before the next one can be found. If the stream deserializer fails, all further calls fail.

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

Checks if another value follows.

Returns Status::Ready if a value follows (it does not need to be complete), Status::End if there are no more values and Status::NeedInput if more input is needed to know. The value is then read with drive_partial or, once poll reports it’s complete, with deserialize. If the stream deserializer cannot find the start of a value on its own (see StreamDeserializer::peek), the value is framed which means that it’s buffered completely.

pub fn supports_partial(&self) -> bool

Returns true if the stream deserializer can deserialize values while their input arrives.

See StreamDeserializer::supports_partial and drive_partial.

pub fn drive_partial( &mut self, driver: &mut DeserializeDriver<'_, '_>, ) -> Result<Status, Error>

Deserializes the next value in parts while its input arrives.

This is the alternative to poll and deserialize for stream deserializers which support it (see supports_partial) and values which do not borrow from the input. If the value was framed already (by peek of a format that cannot find the start of a value otherwise), it’s deserialized from its frame. The input is fed into the driver until the value is complete (Status::Ready), the input is consumed as it’s used. If more input is needed (Status::NeedInput) the method has to be invoked again with the same driver once more input was read. In the meantime the buffer cannot be used otherwise. After an error the value is abandoned, whether the stream can continue with the next value depends on the stream deserializer.

use deser::de::DeserializeDriver;
use deser::stream::{InputBuffer, Status};

// `Digits` is the stream deserializer of a format with a sequence
// of digits
let mut buffer = InputBuffer::new(Digits::default());
let mut out = None::<Vec<u32>>;
{
    let mut driver = DeserializeDriver::new(&mut out);
    for chunk in [&b"12"[..], b"3"] {
        buffer.extend_from_slice(chunk);
        assert_eq!(buffer.drive_partial(&mut driver).unwrap(), Status::NeedInput);
    }
    buffer.set_eof();
    assert_eq!(buffer.drive_partial(&mut driver).unwrap(), Status::Ready);
}
assert_eq!(out.unwrap(), [1, 2, 3]);

Panics

Panics if the stream deserializer does not support partial deserialization.

pub fn read_buf(&mut self) -> &mut [u8]

Returns the buffer to read the next input into.

After data was placed in the buffer, filled has to be called with its length. The buffer is never empty.

pub fn filled(&mut self, len: usize)

Adds data that was read into read_buf.

Panics

Panics if the length exceeds the buffer or if the end of the stream was reached.

pub fn set_eof(&mut self)

Marks the end of the stream.

pub fn extend_from_slice(&mut self, input: &[u8])

Adds input by copying it into the buffer.

This is an alternative to read_buf and filled for input that is already in memory.

pub fn deserialize<'a, T: Deserialize<'a>>(&'a mut self) -> Result<T, Error>

Deserializes the ready value.

The value can borrow from the buffer.

Panics

Panics if no value is ready (see poll).

pub fn deserialize_with<'a, T, F>(&'a mut self, setup: F) -> Result<T, Error>

where T: Deserialize<'a>, F: FnOnce(&mut DeserializeDriver<'_, 'a>),

Deserializes the ready value with a configured driver.

The callback is invoked with the driver before the value is deserialized, for instance to add Layers.

Panics

Panics if no value is ready (see poll).

pub fn drive<'a>( &'a mut self, driver: &mut DeserializeDriver<'_, 'a>, ) -> Result<(), Error>

Feeds the events of the ready value into a driver.

This is useful to deserialize into a custom Sink. The value can borrow from the buffer. To feed it into a driver which outlives the buffer’s data (for instance to implement Deserializer for a reader), lend the driver out with DeserializeDriver::transient:

fn drive<D: StreamDeserializer>(
    buffer: &mut InputBuffer<D>,
    driver: &mut DeserializeDriver<'_, '_>,
) -> Result<(), Error> {
    driver.transient(|driver| buffer.drive(driver))
}

Panics

Panics if no value is ready (see poll).

pub fn trailing_error(&self) -> Error

Creates the error for a value where none is expected.

The error refers to the start of the ready value. Adapters use this to check that a stream ends after a value (see Reader::end of deser::io).

Panics

Panics if no value is ready (see poll).