# DivBuf

A library providing recursively divisible buffer objects.

[![Build Status](https://travis-ci.org/asomers/divbuf.svg?branch=master)](https://travis-ci.org/asomers/divbuf)
[![Crates.io](https://img.shields.io/crates/v/divbuf.svg?maxAge=2592000)](https://crates.io/crates/divbuf)

[Documentation](https://docs.rs/divbuf)

The `divbuf` crate provides a buffer structure `DivBufShared` that can be
efficiently and safely divided into multiple smaller buffers.  Each child buffer
can be further divided, recursively.  A primitive form of range-locking is
available: there is no way to create overlapping mutable child buffers.

This crate is similar to [`bytes`](https://crates.io/crates/bytes), but with a
few key differences:
- `bytes` is a COW crate.  Data will be shared between multiple objects as
   much as possible, but sometimes the data will be copied to new storage.
   `divbuf`, onthe other hand, will _never_ copy data unless explicitly
   requested.
- A `BytesMut` object always has the sole ability to access its own data.
  Once a `BytesMut` object is created, there is no other way to modify or
  even read its data that doesn't involve that object.  A `DivBufMut`, on
  the other hand, can share its data with a `DivBufShared`.  After that
  `DivBufMut` has been dropped, another can be created from the `DivBufShared`.
- `bytes` contains numerous optimizations for dealing with small arrays,
  such as inline storage.  However, some of those optimizations result in
  data copying, which is anathema to `divbuf`.  `divbuf` therefore does not
  include them, and is optimized for working with large arrays.

# License

`divbuf` is distributed under the MIT license.  See [LICENSE](LICENSE) for
details.
