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};