Trait Buf

Source

pub trait Buf {
    // Required methods
    fn advance(&mut self, n: usize);
    fn chunk(&self) -> &[u8] ⓘ;
    fn remaining(&self) -> usize;
    fn try_copy_to_slice(&mut self, dst: &mut [u8]) -> Result<(), BufUnderflow>;

    // Provided methods
    fn has_remaining(&self) -> bool { ... }
    fn copy_to_slice(&mut self, dst: &mut [u8]) { ... }
}

Expand description

Valid UTF-8 sequence whose bytes may or may not be contiguous in memory.

A Buf is a cursor into an in-memory buffer whose internal representation may be contiguous or split across multiple pieces stored at different memory locations. It can be thought of as an efficient iterator over the bytes of a UTF-8 string. Reading from a Buf advances the cursor position.

The simplest Buf is a &[u8].

§Invariant

A new Buf value must only contain valid UTF-8 byte sequences.

Since a Buf may not be contiguous in memory, and bytes may be consumed in arbitrary quantities, individual method calls like chunk or copy_to_slice might return byte sequences with incomplete UTF-8 characters at the boundaries. However, consuming all bytes from a new Buf from start to finish will always yield valid UTF-8.

§Attribution

The design for this trait, including many method names, examples, and documentation passages, is borrowed from the trait of the same name in the bytes crate, which is licensed under the MIT License.

Note however that unlike bytes::Buf, which can contain arbitrary bytes, this trait only ever contains valid UTF-8 byte sequences.

§Example

use bufjson::Buf;

let mut buf = "hello, world".as_bytes();
let mut dst = [0; 5];

buf.copy_to_slice(&mut dst);
assert_eq!(b"hello", &dst);
assert_eq!(7, buf.remaining());

buf.advance(2);
buf.copy_to_slice(&mut dst);
assert_eq!(b"world", &dst);
assert!(!buf.has_remaining());

Required Methods§

Source

fn advance(&mut self, n: usize)

Advances the internal cursor.

The next call to chunk will return a slice starting n bytes further into the buffer.

§Panics

Panics if n > self.remaining().

§Example

use bufjson::{Buf, IntoBuf};

let mut buf = "hello, world".into_buf();
assert_eq!(b"hello, world", buf);

buf.advance(7);
assert_eq!(b"world", buf);

Source

fn chunk(&self) -> &[u8] ⓘ

Returns a slice of bytes starting at the current position, with length between 0 and remaining.

The returned slice may be shorter than remaining to accommodate non-contiguous internal representations. An empty slice is returned only when remaining returns 0, and is always returned in this case since this method never panics.

Calling chunk does not advance the internal cursor.

§Example

use bufjson::Buf;

let mut buf = "hello, world".as_bytes();
assert_eq!(b"hello, world", buf.chunk());

buf.advance(7);
assert_eq!(b"world", buf.chunk()); // A `chunk` call does not advance the internal cursor...
assert_eq!(b"world", buf.chunk()); // ...so calling it again returns the same value.

use bufjson::{Buf, IntoBuf};

// An empty chunk is returned if, and only if, the `Buf` has no remaining bytes.
assert_eq!(0, "".into_buf().remaining());
assert!("".into_buf().chunk().is_empty());

Source

fn remaining(&self) -> usize

Returns the number of bytes between the current position and the end of the buffer.

This value is always greater than or equal to the length of the slice returned by chunk.

§Example

use bufjson::Buf;

let mut buf = "hello, world".as_bytes();
assert_eq!(12, buf.remaining());

buf.advance(7);
assert_eq!(5, buf.remaining());

Source

fn try_copy_to_slice(&mut self, dst: &mut [u8]) -> Result<(), BufUnderflow>

Copies bytes from self into dst.

Advances the internal cursor by the number of bytes copied.

Returns a buffer underflow error without advancing the cursor if self does not have enough bytes remaining to fill dst.

§Examples

use bufjson::{Buf, IntoBuf};

let mut buf = "hello, world".into_buf();
let mut dst = [0; 5];

assert_eq!(Ok(()), buf.try_copy_to_slice(&mut dst));
assert_eq!(b"hello", &dst);
assert_eq!(7, buf.remaining());

use bufjson::{Buf, BufUnderflow};

let mut dst = [0; 13];

assert_eq!(
    Err(BufUnderflow { requested: 13, remaining: 12 }),
    "hello, world".as_bytes().try_copy_to_slice(&mut dst)
);

Provided Methods§

Source

fn has_remaining(&self) -> bool

Returns true if there are more bytes to consume.

This is a convenience method equivalent to self.remaining() > 0.

§Example

use bufjson::Buf;

let mut buf = "hello, world".as_bytes();
assert!(buf.has_remaining());

buf.advance(12);
assert!(!buf.has_remaining());

Source

fn copy_to_slice(&mut self, dst: &mut [u8])

Copies bytes from self into dst.

Advances the internal cursor by the number of bytes copied.

§Panics

Panics if self does not have enough bytes remaining to fill dst.

§Examples

use bufjson::Buf;

let mut buf = "hello, world".as_bytes();
let mut dst = [0; 5];

buf.copy_to_slice(&mut dst);
assert_eq!(b"hello", &dst);
assert_eq!(7, buf.remaining());