Circular

Circular is a stream abstraction designed for use with nom. It can expose the available data, a mutable slice of the available space, and it separates reading data from actually consuming it from the buffer.

lib.rs:

Circular, a stream abstraction designed for use with nom

Circular provides a Buffer type that wraps a Vec<u8> with a position and end. Compared to a stream abstraction that would use std::io::Read, it separates the reading and consuming phases. Read is designed to write the data in a mutable slice and consume it from the stream as it does that.

When used in streaming mode, nom will try to parse a slice, then tell you how much it consumed. So you don't know how much data was actually used until the parser returns. Circular::Buffer exposes a data() method that gives an immutable slice of all the currently readable data, and a consume() method to advance the position in the stream. The space() and fill() methods are the write counterparts to those methods.

extern crate circular;

use circular::Buffer;
use std::io::Write;

fn main() {

  // allocate a new Buffer
  let mut b = Buffer::with_capacity(10);
  assert_eq!(b.available_data(), 0);
  assert_eq!(b.available_space(), 10);

  let res = b.write(&b"abcd"[..]);
  assert_eq!(res.ok(), Some(4));
  assert_eq!(b.available_data(), 4);
  assert_eq!(b.available_space(), 6);

  //the 4 bytes we wrote are immediately available and usable for parsing
  assert_eq!(b.data(), &b"abcd"[..]);

  // this will advance the position from 0 to 2. it does not modify the underlying Vec
  b.consume(2);
  assert_eq!(b.available_data(), 2);
  assert_eq!(b.available_space(), 6);
  assert_eq!(b.data(), &b"cd"[..]);

  // shift moves the available data at the beginning of the buffer.
  // the position is now 0
  b.shift();
  assert_eq!(b.available_data(), 2);
  assert_eq!(b.available_space(), 8);
  assert_eq!(b.data(), &b"cd"[..]);
}