vendor/bytes/src/lib.rs

   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
  78 extern crate alloc;
  79
  80 #[cfg(feature = "std")]
  81 extern crate std;
  82
  83 pub mod buf;
  84 pub use crate::buf::{Buf, BufMut};
  85
  86 mod bytes;
  87 mod bytes_mut;
  88 mod fmt;
  89 mod loom;
  90 pub use crate::bytes::Bytes;
  91 pub use crate::bytes_mut::BytesMut;
  92
  93 // Optional Serde support
  94 #[cfg(feature = "serde")]
  95 mod serde;
  96
  97 #[inline(never)]
  98 #[cold]
  99 fn 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 }