Crate zbuf [−] [src]
BytesBuf and StrBuf
are “zero-copy”[1] buffers.
They are semantically equivalent to Vec<u8> and String respectively
(they derefence to &[u8] / &str, they are mutable and growable),
but have optimizations that minimize the number of data copies and memory allocations required.
- Inline buffers (a.k.a. small string optimization): Small buffers (up to 15 bytes on 64-bit platforms, up to 11 bytes on 32-bit platforms) are stored inline and do not allocate heap memory.
- Reference counting: Multiple buffers can refer to the same reference-counted heap allocation. Cloning a buffer is cheap: it never allocates, at most it increments a reference count.
- Slicing without borrowing: A buffer can be a sub-slice of another without being tied to its lifetime, nor allocating more heap memory.
Limitations:
- Up to 4 GB:
To keep the
std::mem::size_of()of buffers more compact, sizes are stored asu32internally. Trying to allocate more than 4 gigabytes will panic, even on 64-bit platforms with enough RAM available. - No cheap conversions with standard library vectors:
In heap-allocated buffers the data is stored next to a header of metadata.
Conversion to or from
Vec<u8>/Box<[u8]>/String/Box<str>therefore necessarily goes through slices and incurs and data copy and memory allocation.
[1] Disclaimer: we use “zero-copy” with quotes because it is an exaggeration. In typical usage there is at least one copy, for example from the kernel’s network stack to a newly allocated buffer. However, the library’s design is intended to minimize the number of copies needed after that.
Structs
| BytesBuf |
A “zero copy” bytes buffer. |
| FromUtf8Error |
The error type for |
| LossyUtf8Decoder |
A “zero-copy” incremental lossy UTF-8 decoder. |
| StrBuf |
A “zero copy” string buffer. |
| StrictUtf8Decoder |
A “zero-copy” incremental strict UTF-8 decoder. |
| Utf8DecoderError |
The error type for |