Enum iobuf::BufSpan

pub enum BufSpan<Buf> {
    Empty,
    One(Buf),
    Many(Vec<Buf>),
}

A span over potentially many Iobufs. This is useful as a "string" type where the contents of the string can come from multiple IObufs, and you want to avoid copying the buffer contents unnecessarily.

As an optimization, pushing an Iobuf that points to data immediately after the range represented by the last Iobuf pushed will result in just expanding the held Iobuf's range. This prevents allocating lots of unnecessary intermediate buffers, while still maintaining the illusion of "pushing lots of buffers" while incrementally parsing.

A BufSpan is internally represented as either an Iobuf or a Vec<Iobuf>, depending on how many different buffers were used.

Variants

Empty

A span over 0 bytes.

One(Buf)

A single span over one range.

Many(Vec<Buf>)

A span over several backing Iobufs.

Methods

impl<Buf: Iobuf> BufSpan<Buf>

fn new() -> Self

Creates a new, empty Bufspan.

use iobuf::{BufSpan, ROIobuf};

let s: BufSpan<ROIobuf<'static>> = BufSpan::new();
assert!(s.is_empty());

fn from_buf(b: Buf) -> Self

Creates a new BufSpan from an Iobuf.

use iobuf::{BufSpan, ROIobuf};
use std::iter::IntoIterator;

let s = BufSpan::from_buf(ROIobuf::from_slice(b"hello"));
assert_eq!((&s).into_iter().count(), 1);
assert_eq!(s.count_bytes(), 5);

fn is_empty(&self) -> bool

Returns true iff the span is over an empty range.

use iobuf::{BufSpan, Iobuf, ROIobuf};

let mut s = BufSpan::new();

assert!(s.is_empty());

s.push(ROIobuf::from_str(""));
assert!(s.is_empty());

s.push(ROIobuf::from_str("hello, world!"));
assert!(!s.is_empty());

fn push(&mut self, b: Buf)

Appends a buffer to a BufSpan. If the buffer is an extension of the previously pushed buffer, the range will be extended. Otherwise, the new non-extension buffer will be added to the end of a vector.

use iobuf::{BufSpan, Iobuf, ROIobuf};
use std::iter::IntoIterator;

let mut s = BufSpan::new();

s.push(ROIobuf::from_str("he"));
s.push(ROIobuf::from_str("llo"));

assert_eq!(s.count_bytes() as usize, "hello".len());
assert_eq!((&s).into_iter().count(), 2);

let mut b0 = ROIobuf::from_str(" world");
let mut b1 = b0.clone();

assert_eq!(b0.resize(2), Ok(()));
assert_eq!(b1.advance(2), Ok(()));

s.push(b0);
s.push(b1);

// b0 and b1 are immediately after each other, and from the same buffer,
// so get merged into one Iobuf.
assert_eq!(s.count_bytes() as usize, "hello world".len());
assert_eq!((&s).into_iter().count(), 3);

fn iter_bytes<'a>(&'a self) -> ByteIter<'a, Buf>

Returns an iterator over the bytes in the BufSpan.

fn byte_equal<Buf2: Iobuf>(&self, other: &BufSpan<Buf2>) -> bool

Returns true iff the bytes in this BufSpan are the same as the bytes in the other BufSpan.

use iobuf::{BufSpan, ROIobuf, RWIobuf};

let a = BufSpan::from_buf(ROIobuf::from_str("hello"));
let b = BufSpan::from_buf(RWIobuf::from_str_copy("hello"));

assert!(a.byte_equal(&b));

let mut c = BufSpan::from_buf(ROIobuf::from_str("hel"));
c.push(ROIobuf::from_str("lo"));

assert!(a.byte_equal(&c)); assert!(c.byte_equal(&a));

let d = BufSpan::from_buf(ROIobuf::from_str("helo"));
assert!(!a.byte_equal(&d));

fn byte_equal_slice(&self, other: &[u8]) -> bool

A more efficient version of byte_equal, specialized to work exclusively on slices.

use iobuf::{BufSpan, ROIobuf};

let a = BufSpan::from_buf(ROIobuf::from_str("hello"));

assert!(a.byte_equal_slice(b"hello"));
assert!(!a.byte_equal_slice(b"helo"));

fn count_bytes(&self) -> usize

Counts the number of bytes this BufSpan is over. This is O(self.into_iter().len()).

use iobuf::{BufSpan, ROIobuf};

let mut a = BufSpan::from_buf(ROIobuf::from_str("hello"));
a.push(ROIobuf::from_str(" "));
a.push(ROIobuf::from_str("world"));

assert_eq!(a.count_bytes(), 11); // iterates over the pushed buffers.

fn count_bytes_cmp(&self, other: usize) -> Ordering

Compares the number of bytes in this span with another number, returning how they compare. This is more efficient than calling count_bytes and comparing that result, since we might be able to avoid iterating over all the buffers.

use std::cmp::Ordering;
use iobuf::{BufSpan, ROIobuf};

let mut a = BufSpan::from_buf(ROIobuf::from_str("hello"));
a.push(ROIobuf::from_str(" "));
a.push(ROIobuf::from_str("world"));

assert_eq!(a.count_bytes_cmp(0), Ordering::Greater);
assert_eq!(a.count_bytes_cmp(11), Ordering::Equal);
assert_eq!(a.count_bytes_cmp(9001), Ordering::Less);

fn append(&mut self, other: Self)

Extends this span to include the range denoted by another span.

use iobuf::{BufSpan, ROIobuf};

let mut a = BufSpan::from_buf(ROIobuf::from_str("hello"));
a.push(ROIobuf::from_str(" "));
let mut b = BufSpan::from_buf(ROIobuf::from_str("world"));
b.push(ROIobuf::from_str("!!!"));

a.append(b);

assert!(a.byte_equal_slice(b"hello world!!!"));

fn starts_with(&self, other: &[u8]) -> bool

Returns true if the span begins with the given bytes.

use iobuf::{BufSpan, ROIobuf};

let mut a = BufSpan::from_buf(ROIobuf::from_str("hello"));
a.push(ROIobuf::from_str(" "));
a.push(ROIobuf::from_str("world!"));

assert!(a.starts_with(b""));
assert!(a.starts_with(b"hel"));
assert!(a.starts_with(b"hello "));
assert!(a.starts_with(b"hello wor"));
assert!(a.starts_with(b"hello world!"));

assert!(!a.starts_with(b"goodbye"));

fn ends_with(&self, other: &[u8]) -> bool

Returns true if the span ends with the given bytes.

use iobuf::{BufSpan, ROIobuf};

let mut a = BufSpan::from_buf(ROIobuf::from_str("hello"));
a.push(ROIobuf::from_str(" "));
a.push(ROIobuf::from_str("world!"));

assert!(a.ends_with(b""));
assert!(a.ends_with(b"!"));
assert!(a.ends_with(b"rld!"));
assert!(a.ends_with(b"lo world!"));
assert!(a.ends_with(b"hello world!"));

assert!(!a.ends_with(b"goodbye"));

Trait Implementations

impl<Buf: Clone> Clone for BufSpan<Buf>

fn clone(&self) -> BufSpan<Buf>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Buf: Iobuf> Debug for BufSpan<Buf>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Buf: Iobuf> FromIterator<Buf> for BufSpan<Buf>

fn from_iter<T>(iterator: T) -> Self where
    T: IntoIterator<Item = Buf>, 

Creates a value from an iterator.

impl<Buf: Iobuf> Extend<Buf> for BufSpan<Buf>

fn extend<I: IntoIterator<Item = Buf>>(&mut self, iterator: I)

Extends a collection with the contents of an iterator.

impl<Buf: Iobuf> IntoIterator for BufSpan<Buf>

type Item = Buf

The type of the elements being iterated over.

type IntoIter = SpanMoveIter<Buf>

Which kind of iterator are we turning this into?

fn into_iter(self) -> SpanMoveIter<Buf>

Creates an iterator from a value.

impl<'a, Buf: Iobuf> IntoIterator for &'a BufSpan<Buf>

type Item = &'a Buf

The type of the elements being iterated over.

type IntoIter = SpanIter<'a, Buf>

Which kind of iterator are we turning this into?

fn into_iter(self) -> SpanIter<'a, Buf>

Creates an iterator from a value.

impl<Buf: Iobuf> PartialEq for BufSpan<Buf>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Buf: Iobuf> Eq for BufSpan<Buf>

impl<Buf: Iobuf> PartialOrd for BufSpan<Buf>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Buf: Iobuf> Ord for BufSpan<Buf>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

🔬 This is a nightly-only experimental API. (ord_max_min)

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

🔬 This is a nightly-only experimental API. (ord_max_min)

Compares and returns the minimum of two values.