vendor/bytes/src/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 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.12")]
  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 #[deprecated]
  96 pub use byteorder::{ByteOrder, BigEndian, LittleEndian};
  97
  98 // Optional Serde support
  99 #[cfg(feature = "serde")]
 100 #[doc(hidden)]
 101 pub mod serde;
 102
 103 // Optional `Either` support
 104 #[cfg(feature = "either")]
 105 mod either;