# Crate bytes

source ·
Expand description

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 contiguous 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<u8>`), but usually a `BytesMut` is used first and written to. For example:

    use bytes::{BytesMut, BufMut};

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

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

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

    let b = buf.split();
    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.

## Re-exports§

- `pub use crate::buf::Buf;`
- `pub use crate::buf::BufMut;`

## Modules§

- buf
  Utilities for working with buffers.

## Structs§

- Bytes
  A cheaply cloneable and sliceable chunk of contiguous memory.
- BytesMut
  A unique reference to a contiguous slice of memory.
- TryGetError
  Error type for the `try_get_` methods of `Buf`. Indicates that there were not enough remaining bytes in the buffer while attempting to get a value from a `Buf` with one of the `try_get_` methods.