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