embedrs_bytes/
lib.rs

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

embedrs_bytes/
lib.rs
