byteyarn/
lib.rs

1//! `byteyarn` - Space-efficient byte strings 🧶🐈‍⬛
2//!
3//! A [`Yarn`] is a highly optimized string type that provides a number of
4//! useful properties over [`String`]:
5//!
6//! * Always two pointers wide, so it is always passed into and out of functions
7//!   in registers.
8//! * Small string optimization (SSO) up to 15 bytes on 64-bit architectures.
9//! * Can be either an owned buffer or a borrowed buffer (like [`Cow<str>`]).
10//! * Can be upcast to `'static` lifetime if it was constructed from a
11//!   known-static string.
12//! * `Option<Yarn>` has the same size and ABI as `Yarn`.
13//!
14//! The main caveat is that [`Yarn`]s cannot be easily appended to, since they
15//! do not track an internal capacity, and the slice returned by
16//! [`Yarn::as_slice()`] does not have the same pointer stability properties as
17//! [`String`] (these are rarely needed, though).
18//!
19//! ---
20//!
21//! Yarns are useful for situations in which a copy-on-write string is necessary
22//! and most of the strings are relatively small. Although [`Yarn`] itself is
23//! not [`Copy`], there is a separate [`YarnRef`] type that is. These types
24//! have equivalent representations, and can be cheaply cast between each other.
25//!
26//! The easiest way to create a yarn is with the [`yarn!()`]
27//! macro, which is similar to [`format!()`].
28//!
29//! ```
30//! # use byteyarn::*;
31//! // Create a new yarn via `fmt`ing.
32//! let yarn = yarn!("Answer: {}", 42);
33//!
34//! // Convert that yarn into a reference.
35//! let ry: YarnRef<str> = yarn.as_ref();
36//!
37//! // Try up-casting the yarn into an "immortal yarn" without copying.
38//! let copy: YarnRef<'static, str> = ry.immortalize().unwrap();
39//!
40//! assert_eq!(yarn, copy);
41//! ```
42//!
43//! Yarns are intended for storing text, either as UTF-8 or as
44//! probably-UTF-8 bytes; [`Yarn<str>`] and [`Yarn<[u8]>`] serve these purposes,
45//! and can be inter-converted with each other. The [`Yarn::utf8_chunks()`]
46//! function can be used to iterate over definitely-valid-UTF-8 chunks within
47//! a string.
48//!
49//! Both kinds of yarns can be `Debug`ed and `Display`ed, and will print out as
50//! strings would. In particular, invalid UTF-8 is converted into either `\xNN`
51//! escapes or replacement characters (for `Debug` and `Display` respectively).
52//!
53//! ```
54//! # use byteyarn::*;
55//! let invalid = ByteYarn::from_byte(0xff);
56//! assert_eq!(format!("{invalid:?}"), r#""\xFF""#);
57//! assert_eq!(format!("{invalid}"), "�");
58//! ```
59//!
60//! That said, they will support anything that implements the [`Buf`] trait.
61//! For example, you can have 16-bit yarns:
62//!
63//! ```
64//! # use byteyarn::*;
65//!
66//! let sixteen = YarnBox::<[u16]>::from([1, 2, 3, 4, 5, 6, 8, 9, 10, 11]);
67//! assert_eq!(sixteen[2], 3u16);
68//! ```
69
70#![deny(missing_docs)]
71
72#[cfg(doc)]
73use std::borrow::Cow;
74
75mod boxed;
76mod convert;
77mod raw;
78mod reffed;
79mod utf8;
80
81pub use boxed::YarnBox;
82pub use reffed::YarnRef;
83pub use utf8::Utf8Chunks;
84
85pub use buf_trait::Buf;
86
87// Macro stuff.
88#[doc(hidden)]
89pub mod m {
90  pub extern crate std;
91}
92
93/// An optimized Unicode string.
94///
95/// See [`YarnBox`] for full type documentation.
96pub type Yarn = YarnBox<'static, str>;
97
98/// An optimized raw byte string.
99///
100/// See [`YarnBox`] for full type documentation.
101pub type ByteYarn = YarnBox<'static, [u8]>;
102
103/// Similar to [`format!()`], but returns a [`Yarn`], instead.
104///
105/// This macro calls out to [`Yarn::from_fmt()`] internally.
106#[macro_export]
107macro_rules! yarn {
108  ($($args:tt)*) => {
109    $crate::Yarn::from_fmt($crate::m::std::format_args!($($args)*))
110  };
111}
byteyarn/lib.rs

byteyarn/
lib.rs
