bytes/
lib.rs

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

bytes/
lib.rs
