ntex_bytes/
lib.rs

1//! Provides abstractions for working with bytes.
2//!
3//! The `ntex-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 contiguous
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 `BytesMut` store
22//! is used first and written to. For example:
23//!
24//! ```rust
25//! use ntex_bytes::{BytesMut, BufMut};
26//!
27//! let mut buf = BytesMut::with_capacity(1024);
28//! buf.put(&b"hello world"[..]);
29//! buf.put_u16(1234);
30//!
31//! let a = buf.take();
32//! assert_eq!(a, b"hello world\x04\xD2"[..]);
33//!
34//! buf.put(&b"goodbye world"[..]);
35//!
36//! let b = buf.take();
37//! assert_eq!(b, b"goodbye world"[..]);
38//!
39//! assert_eq!(buf.capacity(), 998);
40//! ```
41//!
42//! In the above example, only a single buffer of 1024 is allocated. The handles
43//! `a` and `b` will share the underlying buffer and maintain indices tracking
44//! the view into the buffer represented by the handle.
45//!
46//! See the [struct docs] for more details.
47//!
48//! [struct docs]: struct.Bytes.html
49//!
50#![doc(html_root_url = "https://docs.rs/ntex-bytes/")]
51#![deny(clippy::pedantic)]
52#![allow(
53    unsafe_op_in_unsafe_fn,
54    clippy::must_use_candidate,
55    clippy::cast_sign_loss,
56    clippy::cast_possible_wrap,
57    clippy::cast_possible_truncation
58)]
59
60extern crate alloc;
61
62pub mod buf;
63pub use crate::buf::{Buf, BufMut};
64
65mod bvec;
66mod bytes;
67mod debug;
68mod hex;
69mod pages;
70mod serde;
71mod storage;
72mod string;
73
74pub use crate::bvec::BytesMut;
75pub use crate::bytes::Bytes;
76pub use crate::pages::{BytePage, BytePages};
77pub use crate::string::ByteString;
78
79#[doc(hidden)]
80pub use crate::storage::METADATA_SIZE;
81
82#[doc(hidden)]
83#[deprecated]
84pub type BytesVec = BytesMut;
85
86#[doc(hidden)]
87pub mod info {
88    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
89    pub struct Info {
90        pub id: usize,
91        pub refs: u32,
92        pub kind: Kind,
93        pub capacity: usize,
94    }
95
96    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
97    pub enum Kind {
98        Inline,
99        Static,
100        Vec,
101    }
102}
103
104#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
105pub enum BytePageSize {
106    Size4 = 0,
107    Size8 = 1,
108    #[default]
109    Size16 = 2,
110    Size24 = 3,
111    Size32 = 4,
112    Size48 = 5,
113    Size64 = 6,
114    Unset = 7,
115}
116
117impl BytePageSize {
118    const fn capacity(self) -> usize {
119        match self {
120            BytePageSize::Size4 => 4 * 1024,
121            BytePageSize::Size8 => 8 * 1024,
122            BytePageSize::Size16 => 16 * 1024,
123            BytePageSize::Size24 => 24 * 1024,
124            BytePageSize::Size32 => 32 * 1024,
125            BytePageSize::Size48 => 48 * 1024,
126            BytePageSize::Size64 | BytePageSize::Unset => 64 * 1024,
127        }
128    }
129}
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    #[test]
136    fn page_size() {
137        assert_eq!(BytePageSize::Size4.capacity(), 4 * 1024);
138        assert_eq!(BytePageSize::Size8.capacity(), 8 * 1024);
139        assert_eq!(BytePageSize::Size16.capacity(), 16 * 1024);
140        assert_eq!(BytePageSize::Size24.capacity(), 24 * 1024);
141        assert_eq!(BytePageSize::Size32.capacity(), 32 * 1024);
142        assert_eq!(BytePageSize::Size48.capacity(), 48 * 1024);
143        assert_eq!(BytePageSize::Size64.capacity(), 64 * 1024);
144        assert_eq!(BytePageSize::Unset.capacity(), 64 * 1024);
145    }
146}
ntex_bytes/lib.rs

ntex_bytes/
lib.rs
