3 releases (breaking)

Uses old Rust 2015

0.3.0 Jun 28, 2019
0.2.0 May 8, 2017
0.1.0 May 4, 2017

#448 in Parser implementations

Download history 6257/week @ 2022-12-02 6000/week @ 2022-12-09 5896/week @ 2022-12-16 2707/week @ 2022-12-23 3810/week @ 2022-12-30 6079/week @ 2023-01-06 6278/week @ 2023-01-13 5686/week @ 2023-01-20 6876/week @ 2023-01-27 6248/week @ 2023-02-03 6691/week @ 2023-02-10 6143/week @ 2023-02-17 6277/week @ 2023-02-24 6351/week @ 2023-03-03 10750/week @ 2023-03-10 7829/week @ 2023-03-17

32,281 downloads per month
Used in 42 crates (8 directly)

MIT license

253 lines


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.


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
  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
  assert_eq!(b.available_data(), 2);
  assert_eq!(b.available_space(), 8);
  assert_eq!(b.data(), &b"cd"[..]);

No runtime deps