| 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"[..]);
}
|
12469 |