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 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/bytes/0.4")] 73 74 extern crate byteorder; 75 extern crate iovec; 76 77 pub mod buf; 78 pub use buf::{ 79 Buf, 80 BufMut, 81 IntoBuf, 82 }; 83 #[deprecated(since = "0.4.1", note = "moved to `buf` module")] 84 #[doc(hidden)] 85 pub use buf::{ 86 Reader, 87 Writer, 88 Take, 89 }; 90 91 mod bytes; 92 mod debug; 93 pub use bytes::{Bytes, BytesMut}; 94 95 pub use byteorder::{ByteOrder, BigEndian, LittleEndian}; 96 97 // Optional Serde support 98 #[cfg(feature = "serde")] 99 #[doc(hidden)] 100 pub mod serde; 101