divbuf/
lib.rs

1// vim: tw=80
2
3//! Recursively divisible buffer class
4//!
5//! The `divbuf` crate provides a buffer structure
6//! ([`DivBufShared`](struct.DivBufShared.html)) that can be efficiently and
7//! safely divided into multiple smaller buffers.  Each child buffer can be
8//! further divided, recursively.  A primitive form of range-locking is
9//! available: there is no way to create overlapping mutable child buffers.
10//!
11//! This crate is similar to [`bytes`], but with a few key differences:
12//! - `bytes` is a COW crate.  Data will be shared between multiple objects as
13//!   much as possible, but sometimes the data will be copied to new storage.
14//!   `divbuf`, onthe other hand, will _never_ copy data unless explicitly
15//!   requested.
16//! - A `BytesMut` object always has the sole ability to access its own data.
17//!   Once a `BytesMut` object is created, there is no other way to modify or
18//!   even read its data that doesn't involve that object.  A `DivBufMut`, on
19//!   the other hand, shares its data with its parent `DivBufShared`.  After
20//!   that `DivBufMut` has been dropped, another can be created from the
21//!   parent.
22//! - `bytes` contains numerous optimizations for dealing with small arrays,
23//!   such as inline storage.  However, some of those optimizations result in
24//!   data copying, which is anathema to `divbuf`.  `divbuf` therefore does not
25//!   include them, and is optimized for working with large arrays.
26//!
27//! # Examples
28//! ```
29//! use divbuf::*;
30//!
31//! let v = String::from("Some Green Stuff").into_bytes();
32//! let dbs = DivBufShared::from(v);
33//! {
34//!     let mut dbm = dbs.try_mut().unwrap();
35//!     let mut right_half = dbm.split_off(5);
36//!     let mut color_buffer = right_half.split_to(5);
37//!     color_buffer[..].copy_from_slice(&b"Black"[..]);
38//! }
39//! let db = dbs.try_const().unwrap();
40//! assert_eq!(db, b"Some Black Stuff"[..]);
41//! ```
42//!
43//! [`bytes`]: https://carllerche.github.io/bytes/bytes/index.html
44#![cfg_attr(docsrs, feature(doc_cfg))]
45#![deny(warnings, missing_docs, missing_debug_implementations)]
46
47mod divbuf;
48
49pub use self::divbuf::{
50    Chunks,
51    ChunksMut,
52    DivBuf,
53    DivBufInaccessible,
54    DivBufMut,
55    DivBufShared,
56};