Crate bytes [−] [src]

Provides abstractions for working with bytes.

The bytes crate provides an efficient byte buffer structure (Bytes) and traits for working with buffer implementations (Buf, BufMut).

`Bytes`

Bytes is an efficient container for storing and operating on continguous slices of memory. It is intended for use primarily in networking code, but could have applications elsewhere as well.

Bytes values facilitate zero-copy network programming by allowing multiple Bytes objects to point to the same underlying memory. This is managed by using a reference count to track when the memory is no longer needed and can be freed.

A Bytes handle can be created directly from an existing byte store (such as &[u8] or Vec), but usually a BytesMut is used first and written to. For example:

use bytes::{BytesMut, BufMut, BigEndian};

let mut buf = BytesMut::with_capacity(1024);
buf.put(&b"hello world"[..]);
buf.put_u16::<BigEndian>(1234);

let a = buf.take();
assert_eq!(a, b"hello world\x04\xD2"[..]);

buf.put(&b"goodbye world"[..]);

let b = buf.take();
assert_eq!(b, b"goodbye world"[..]);

assert_eq!(buf.capacity(), 998);

In the above example, only a single buffer of 1024 is allocated. The handles a and b will share the underlying buffer and maintain indices tracking the view into the buffer represented by the handle.

See the struct docs for more details.

`Buf`, `BufMut`

These two traits provide read and write access to buffers. The underlying storage may or may not be in contiguous memory. For example, Bytes is a buffer that guarantees contiguous memory, but a rope stores the bytes in disjoint chunks. Buf and BufMut maintain cursors tracking the current position in the underlying byte storage. When bytes are read or written, the cursor is advanced.

Relation with `Read` and `Write`

At first glance, it may seem that Buf and BufMut overlap in functionality with std::io::Read and std::io::Write. However, they serve different purposes. A buffer is the value that is provided as an argument to Read::read and Write::write. Read and Write may then perform a syscall, which has the potential of failing. Operations on Buf and BufMut are infallible.

Modules

buf	Utilities for working with buffers.

Structs

Bytes	A reference counted contiguous slice of memory.
BytesMut	A unique reference to a contiguous slice of memory.

Enums

BigEndian	Defines big-endian serialization.
LittleEndian	Defines little-endian serialization.

Traits

Buf	Read bytes from a buffer.
BufMut	A trait for values that provide sequential write access to bytes.
ByteOrder	ByteOrder describes types that can serialize integers as bytes.
IntoBuf	Conversion into a `Buf`