scolapasta_strbuf/
lib.rs

1#![warn(clippy::all, clippy::pedantic, clippy::undocumented_unsafe_blocks)]
2#![allow(
3    clippy::let_underscore_untyped,
4    reason = "https://github.com/rust-lang/rust-clippy/pull/10442#issuecomment-1516570154"
5)]
6#![allow(
7    clippy::question_mark,
8    reason = "https://github.com/rust-lang/rust-clippy/issues/8281"
9)]
10#![allow(clippy::manual_let_else, reason = "manual_let_else was very buggy on release")]
11#![allow(clippy::missing_errors_doc, reason = "A lot of existing code fails this lint")]
12#![allow(
13    clippy::unnecessary_lazy_evaluations,
14    reason = "https://github.com/rust-lang/rust-clippy/issues/8109"
15)]
16#![cfg_attr(
17    test,
18    allow(clippy::non_ascii_literal, reason = "tests sometimes require UTF-8 string content")
19)]
20#![allow(unknown_lints)]
21#![warn(
22    missing_copy_implementations,
23    missing_debug_implementations,
24    missing_docs,
25    rust_2024_compatibility,
26    trivial_casts,
27    trivial_numeric_casts,
28    unused_qualifications,
29    variant_size_differences
30)]
31// Enable feature callouts in generated documentation:
32// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
33//
34// This approach is borrowed from tokio.
35#![cfg_attr(docsrs, feature(doc_cfg))]
36#![cfg_attr(docsrs, feature(doc_alias))]
37
38//! A contiguous growable byte string, written as `Buf`, short for "buffer".
39//!
40//! Buffers have *O*(1) indexing, amortized *O*(1) push (to the end) and *O*(1)
41//! pop (from the end).
42//!
43//! Buffers ensure they never allocate more than `isize::MAX` bytes.
44//!
45//! Buffers are transparent wrappers around [`Vec<u8>`] with a minimized API
46//! sufficient for implementing the Ruby [`String`] type.
47//!
48//! Buffers do not assume any encoding. Encoding is a higher-level concept that
49//! should be built on top of `Buf`.
50//!
51//! # Examples
52//!
53//! You can explicitly create a [`Buf`] with [`Buf::new`]:
54//!
55//! ```
56//! use scolapasta_strbuf::Buf;
57//!
58//! let buf = Buf::new();
59//! ```
60//!
61//! You can [`push_byte`] bytes into the end of a buffer (which will grow the
62//! buffer as needed):
63//!
64//! ```
65//! use scolapasta_strbuf::Buf;
66//!
67//! let mut buf = Buf::from(b"12");
68//!
69//! buf.push_byte(b'3');
70//! assert_eq!(buf, b"123");
71//! ```
72//!
73//! Popping bytes works in much the same way:
74//!
75//! ```
76//! use scolapasta_strbuf::Buf;
77//!
78//! let mut buf = Buf::from(b"12");
79//!
80//! let alpha_two = buf.pop_byte();
81//! assert_eq!(alpha_two, Some(b'2'));
82//! ```
83//!
84//! Buffers also support indexing (through the [`Index`] and [`IndexMut`]
85//! traits):
86//!
87//! ```
88//! use scolapasta_strbuf::Buf;
89//!
90//! let mut buf = Buf::from(b"123");
91//! let three = buf[2];
92//! buf[1] = b'!';
93//! ```
94//!
95//! # Crate features
96//!
97//! - **std**: Enabled by default. Implement [`std::io::Write`] for `Buf`. If
98//!   this feature is disabled, this crate only depends on [`alloc`].
99//! - **nul-terminated**: Use an alternate byte buffer backend that ensures
100//!   byte content is always followed by a NUL byte in the buffer's spare
101//!   capacity. This feature can be used to ensure `Buf`s are FFI compatible
102//!   with C code that expects byte content to be NUL terminated.
103//!
104//! [`Vec<u8>`]: alloc::vec::Vec
105//! [`String`]: https://ruby-doc.org/3.2.0/String.html
106#![cfg_attr(
107    not(feature = "std"),
108    doc = "[`std::io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html"
109)]
110//! [`push_byte`]: Buf::push_byte
111//! [`Index`]: core::ops::Index
112//! [`IndexMut`]: core::ops::IndexMut
113
114#![no_std]
115
116// Ensure code blocks in `README.md` compile
117#[cfg(doctest)]
118#[doc = include_str!("../README.md")]
119mod readme {}
120
121extern crate alloc;
122#[cfg(feature = "std")]
123extern crate std;
124
125macro_rules! impl_partial_eq {
126    ($lhs:ty, $rhs:ty) => {
127        impl<'a, 'b> PartialEq<$rhs> for $lhs {
128            #[inline]
129            fn eq(&self, other: &$rhs) -> bool {
130                let other: &[u8] = other.as_ref();
131                PartialEq::eq(self.as_slice(), other)
132            }
133        }
134
135        impl<'a, 'b> PartialEq<$lhs> for $rhs {
136            #[inline]
137            fn eq(&self, other: &$lhs) -> bool {
138                let this: &[u8] = self.as_ref();
139                PartialEq::eq(this, other.as_slice())
140            }
141        }
142    };
143}
144
145macro_rules! impl_partial_eq_array {
146    ($lhs:ty, $rhs:ty) => {
147        impl<'a, 'b, const N: usize> PartialEq<$rhs> for $lhs {
148            #[inline]
149            fn eq(&self, other: &$rhs) -> bool {
150                let other: &[u8] = other.as_ref();
151                PartialEq::eq(self.as_slice(), other)
152            }
153        }
154
155        impl<'a, 'b, const N: usize> PartialEq<$lhs> for $rhs {
156            #[inline]
157            fn eq(&self, other: &$lhs) -> bool {
158                let this: &[u8] = self.as_ref();
159                PartialEq::eq(this, other.as_slice())
160            }
161        }
162    };
163}
164
165pub use raw_parts::RawParts;
166
167mod nul_terminated_vec;
168mod vec;
169
170mod imp {
171    #[cfg(feature = "nul-terminated")]
172    pub use crate::nul_terminated_vec::Buf;
173    #[cfg(not(feature = "nul-terminated"))]
174    pub use crate::vec::Buf;
175}
176
177// Only export one `Buf` type. The presence of the `nul-terminated` feature
178// determines which `Buf` type to use.
179pub use imp::Buf;
scolapasta_strbuf/lib.rs

scolapasta_strbuf/
lib.rs
