1#![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)]
2#![doc(test(
3 no_crate_inject,
4 attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
5))]
6#![no_std]
7#![cfg_attr(docsrs, feature(doc_cfg))]
8
9//! Provides abstractions for working with bytes.
10//!
11//! The `bytes` crate provides an efficient byte buffer structure
12//! ([`Bytes`](struct.Bytes.html)) and traits for working with buffer
13//! implementations ([`Buf`], [`BufMut`]).
14//!
15//! [`Buf`]: trait.Buf.html
16//! [`BufMut`]: trait.BufMut.html
17//!
18//! # `Bytes`
19//!
20//! `Bytes` is an efficient container for storing and operating on contiguous
21//! slices of memory. It is intended for use primarily in networking code, but
22//! could have applications elsewhere as well.
23//!
24//! `Bytes` values facilitate zero-copy network programming by allowing multiple
25//! `Bytes` objects to point to the same underlying memory. This is managed by
26//! using a reference count to track when the memory is no longer needed and can
27//! be freed.
28//!
29//! A `Bytes` handle can be created directly from an existing byte store (such as `&[u8]`
30//! or `Vec<u8>`), but usually a `BytesMut` is used first and written to. For
31//! example:
32//!
33//! ```rust
34//! use bytes::{BytesMut, BufMut};
35//!
36//! let mut buf = BytesMut::with_capacity(1024);
37//! buf.put(&b"hello world"[..]);
38//! buf.put_u16(1234);
39//!
40//! let a = buf.split();
41//! assert_eq!(a, b"hello world\x04\xD2"[..]);
42//!
43//! buf.put(&b"goodbye world"[..]);
44//!
45//! let b = buf.split();
46//! assert_eq!(b, b"goodbye world"[..]);
47//!
48//! assert_eq!(buf.capacity(), 998);
49//! ```
50//!
51//! In the above example, only a single buffer of 1024 is allocated. The handles
52//! `a` and `b` will share the underlying buffer and maintain indices tracking
53//! the view into the buffer represented by the handle.
54//!
55//! See the [struct docs] for more details.
56//!
57//! [struct docs]: struct.Bytes.html
58//!
59//! # `Buf`, `BufMut`
60//!
61//! These two traits provide read and write access to buffers. The underlying
62//! storage may or may not be in contiguous memory. For example, `Bytes` is a
63//! buffer that guarantees contiguous memory, but a [rope] stores the bytes in
64//! disjoint chunks. `Buf` and `BufMut` maintain cursors tracking the current
65//! position in the underlying byte storage. When bytes are read or written, the
66//! cursor is advanced.
67//!
68//! [rope]: https://en.wikipedia.org/wiki/Rope_(data_structure)
69//!
70//! ## Relation with `Read` and `Write`
71//!
72//! At first glance, it may seem that `Buf` and `BufMut` overlap in
73//! functionality with `std::io::Read` and `std::io::Write`. However, they
74//! serve different purposes. A buffer is the value that is provided as an
75//! argument to `Read::read` and `Write::write`. `Read` and `Write` may then
76//! perform a syscall, which has the potential of failing. Operations on `Buf`
77//! and `BufMut` are infallible.
78
79extern crate alloc;
80
81#[cfg(feature = "std")]
82extern crate std;
83
84pub mod buf;
85pub use crate::buf::{Buf, BufMut};
86
87mod bytes;
88mod bytes_mut;
89mod fmt;
90mod loom;
91pub use crate::bytes::Bytes;
92pub use crate::bytes_mut::BytesMut;
93
94// Optional Serde support
95#[cfg(feature = "serde")]
96mod serde;
97
98#[inline(never)]
99#[cold]
100fn abort() -> ! {
101 #[cfg(feature = "std")]
102 {
103 std::process::abort();
104 }
105
106 #[cfg(not(feature = "std"))]
107 {
108 struct Abort;
109 impl Drop for Abort {
110 fn drop(&mut self) {
111 panic!();
112 }
113 }
114 let _a = Abort;
115 panic!("abort");
116 }
117}
118