1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
6#![cfg_attr(all(not(test), not(doc)), no_std)]
7#![cfg_attr(
8 not(test),
9 deny(
10 clippy::indexing_slicing,
11 clippy::unwrap_used,
12 clippy::expect_used,
13 clippy::panic,
14 clippy::exhaustive_structs,
15 clippy::exhaustive_enums,
16 missing_debug_implementations,
17 )
18)]
19
20//! `writeable` is a utility crate of the [`ICU4X`] project.
21//!
22//! It includes [`Writeable`], a core trait representing an object that can be written to a
23//! sink implementing `std::fmt::Write`. It is an alternative to `std::fmt::Display` with the
24//! addition of a function indicating the number of bytes to be written.
25//!
26//! `Writeable` improves upon `std::fmt::Display` in two ways:
27//!
28//! 1. More efficient, since the sink can pre-allocate bytes.
29//! 2. Smaller code, since the format machinery can be short-circuited.
30//!
31//! # Examples
32//!
33//! ```
34//! use std::fmt;
35//! use writeable::assert_writeable_eq;
36//! use writeable::LengthHint;
37//! use writeable::Writeable;
38//!
39//! struct WelcomeMessage<'s> {
40//! pub name: &'s str,
41//! }
42//!
43//! impl<'s> Writeable for WelcomeMessage<'s> {
44//! fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
45//! sink.write_str("Hello, ")?;
46//! sink.write_str(self.name)?;
47//! sink.write_char('!')?;
48//! Ok(())
49//! }
50//!
51//! fn writeable_length_hint(&self) -> LengthHint {
52//! // "Hello, " + '!' + length of name
53//! LengthHint::exact(8 + self.name.len())
54//! }
55//! }
56//!
57//! let message = WelcomeMessage { name: "Alice" };
58//! assert_writeable_eq!(&message, "Hello, Alice!");
59//!
60//! // Types implementing `Writeable` are recommended to also implement `fmt::Display`.
61//! // This can be simply done by redirecting to the `Writeable` implementation:
62//! writeable::impl_display_with_writeable!(WelcomeMessage<'_>);
63//! ```
64//!
65//! [`ICU4X`]: ../icu/index.html
66
67extern crate alloc;
68
69mod cmp;
70#[cfg(feature = "either")]
71mod either;
72mod impls;
73mod ops;
74mod parts_write_adapter;
75mod testing;
76mod try_writeable;
77
78use alloc::borrow::Cow;
79use alloc::string::String;
80use core::fmt;
81
82pub use try_writeable::TryWriteable;
83
84/// Helper types for trait impls.
85pub mod adapters {
86 use super::*;
87
88 pub use parts_write_adapter::CoreWriteAsPartsWrite;
89 pub use try_writeable::TryWriteableInfallibleAsWriteable;
90 pub use try_writeable::WriteableAsTryWriteableInfallible;
91}
92
93#[doc(hidden)]
94pub mod _internal {
95 pub use super::testing::try_writeable_to_parts_for_test;
96 pub use super::testing::writeable_to_parts_for_test;
97}
98
99/// A hint to help consumers of `Writeable` pre-allocate bytes before they call
100/// [`write_to`](Writeable::write_to).
101///
102/// This behaves like `Iterator::size_hint`: it is a tuple where the first element is the
103/// lower bound, and the second element is the upper bound. If the upper bound is `None`
104/// either there is no known upper bound, or the upper bound is larger than `usize`.
105///
106/// `LengthHint` implements std`::ops::{Add, Mul}` and similar traits for easy composition.
107/// During computation, the lower bound will saturate at `usize::MAX`, while the upper
108/// bound will become `None` if `usize::MAX` is exceeded.
109#[derive(Debug, PartialEq, Eq, Copy, Clone)]
110#[non_exhaustive]
111pub struct LengthHint(pub usize, pub Option<usize>);
112
113impl LengthHint {
114 pub fn undefined() -> Self {
115 Self(0, None)
116 }
117
118 /// `write_to` will use exactly n bytes.
119 pub fn exact(n: usize) -> Self {
120 Self(n, Some(n))
121 }
122
123 /// `write_to` will use at least n bytes.
124 pub fn at_least(n: usize) -> Self {
125 Self(n, None)
126 }
127
128 /// `write_to` will use at most n bytes.
129 pub fn at_most(n: usize) -> Self {
130 Self(0, Some(n))
131 }
132
133 /// `write_to` will use between `n` and `m` bytes.
134 pub fn between(n: usize, m: usize) -> Self {
135 Self(Ord::min(n, m), Some(Ord::max(n, m)))
136 }
137
138 /// Returns a recommendation for the number of bytes to pre-allocate.
139 /// If an upper bound exists, this is used, otherwise the lower bound
140 /// (which might be 0).
141 ///
142 /// # Examples
143 ///
144 /// ```
145 /// use writeable::Writeable;
146 ///
147 /// fn pre_allocate_string(w: &impl Writeable) -> String {
148 /// String::with_capacity(w.writeable_length_hint().capacity())
149 /// }
150 /// ```
151 pub fn capacity(&self) -> usize {
152 self.1.unwrap_or(self.0)
153 }
154
155 /// Returns whether the `LengthHint` indicates that the string is exactly 0 bytes long.
156 pub fn is_zero(&self) -> bool {
157 self.1 == Some(0)
158 }
159}
160
161/// [`Part`]s are used as annotations for formatted strings. For example, a string like
162/// `Alice, Bob` could assign a `NAME` part to the substrings `Alice` and `Bob`, and a
163/// `PUNCTUATION` part to `, `. This allows for example to apply styling only to names.
164///
165/// `Part` contains two fields, whose usage is left up to the producer of the [`Writeable`].
166/// Conventionally, the `category` field will identify the formatting logic that produces
167/// the string/parts, whereas the `value` field will have semantic meaning. `NAME` and
168/// `PUNCTUATION` could thus be defined as
169/// ```
170/// # use writeable::Part;
171/// const NAME: Part = Part {
172/// category: "userlist",
173/// value: "name",
174/// };
175/// const PUNCTUATION: Part = Part {
176/// category: "userlist",
177/// value: "punctuation",
178/// };
179/// ```
180///
181/// That said, consumers should not usually have to inspect `Part` internals. Instead,
182/// formatters should expose the `Part`s they produces as constants.
183#[derive(Clone, Copy, Debug, PartialEq)]
184#[allow(clippy::exhaustive_structs)] // stable
185pub struct Part {
186 pub category: &'static str,
187 pub value: &'static str,
188}
189
190impl Part {
191 /// A part that should annotate error segments in [`TryWriteable`] output.
192 ///
193 /// For an example, see [`TryWriteable`].
194 pub const ERROR: Part = Part {
195 category: "writeable",
196 value: "error",
197 };
198}
199
200/// A sink that supports annotating parts of the string with `Part`s.
201pub trait PartsWrite: fmt::Write {
202 type SubPartsWrite: PartsWrite + ?Sized;
203
204 fn with_part(
205 &mut self,
206 part: Part,
207 f: impl FnMut(&mut Self::SubPartsWrite) -> fmt::Result,
208 ) -> fmt::Result;
209}
210
211/// `Writeable` is an alternative to `std::fmt::Display` with the addition of a length function.
212pub trait Writeable {
213 /// Writes a string to the given sink. Errors from the sink are bubbled up.
214 /// The default implementation delegates to `write_to_parts`, and discards any
215 /// `Part` annotations.
216 fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
217 self.write_to_parts(&mut parts_write_adapter::CoreWriteAsPartsWrite(sink))
218 }
219
220 /// Write bytes and `Part` annotations to the given sink. Errors from the
221 /// sink are bubbled up. The default implementation delegates to `write_to`,
222 /// and doesn't produce any `Part` annotations.
223 fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
224 self.write_to(sink)
225 }
226
227 /// Returns a hint for the number of UTF-8 bytes that will be written to the sink.
228 ///
229 /// Override this method if it can be computed quickly.
230 fn writeable_length_hint(&self) -> LengthHint {
231 LengthHint::undefined()
232 }
233
234 /// Creates a new `String` with the data from this `Writeable`. Like `ToString`,
235 /// but smaller and faster.
236 ///
237 /// The default impl allocates an owned `String`. However, if it is possible to return a
238 /// borrowed string, overwrite this method to return a `Cow::Borrowed`.
239 ///
240 /// To remove the `Cow` wrapper, call `.into_owned()` or `.as_str()` as appropriate.
241 ///
242 /// # Examples
243 ///
244 /// Inspect a `Writeable` before writing it to the sink:
245 ///
246 /// ```
247 /// use core::fmt::{Result, Write};
248 /// use writeable::Writeable;
249 ///
250 /// fn write_if_ascii<W, S>(w: &W, sink: &mut S) -> Result
251 /// where
252 /// W: Writeable + ?Sized,
253 /// S: Write + ?Sized,
254 /// {
255 /// let s = w.write_to_string();
256 /// if s.is_ascii() {
257 /// sink.write_str(&s)
258 /// } else {
259 /// Ok(())
260 /// }
261 /// }
262 /// ```
263 ///
264 /// Convert the `Writeable` into a fully owned `String`:
265 ///
266 /// ```
267 /// use writeable::Writeable;
268 ///
269 /// fn make_string(w: &impl Writeable) -> String {
270 /// w.write_to_string().into_owned()
271 /// }
272 /// ```
273 fn write_to_string(&self) -> Cow<str> {
274 let hint = self.writeable_length_hint();
275 if hint.is_zero() {
276 return Cow::Borrowed("");
277 }
278 let mut output = String::with_capacity(hint.capacity());
279 let _ = self.write_to(&mut output);
280 Cow::Owned(output)
281 }
282
283 /// Compares the contents of this `Writeable` to the given bytes
284 /// without allocating a String to hold the `Writeable` contents.
285 ///
286 /// This returns a lexicographical comparison, the same as if the Writeable
287 /// were first converted to a String and then compared with `Ord`. For a
288 /// locale-sensitive string ordering, use an ICU4X Collator.
289 ///
290 /// # Examples
291 ///
292 /// ```
293 /// use core::cmp::Ordering;
294 /// use core::fmt;
295 /// use writeable::Writeable;
296 ///
297 /// struct WelcomeMessage<'s> {
298 /// pub name: &'s str,
299 /// }
300 ///
301 /// impl<'s> Writeable for WelcomeMessage<'s> {
302 /// // see impl in Writeable docs
303 /// # fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
304 /// # sink.write_str("Hello, ")?;
305 /// # sink.write_str(self.name)?;
306 /// # sink.write_char('!')?;
307 /// # Ok(())
308 /// # }
309 /// }
310 ///
311 /// let message = WelcomeMessage { name: "Alice" };
312 /// let message_str = message.write_to_string();
313 ///
314 /// assert_eq!(Ordering::Equal, message.writeable_cmp_bytes(b"Hello, Alice!"));
315 ///
316 /// assert_eq!(Ordering::Greater, message.writeable_cmp_bytes(b"Alice!"));
317 /// assert_eq!(Ordering::Greater, (*message_str).cmp("Alice!"));
318 ///
319 /// assert_eq!(Ordering::Less, message.writeable_cmp_bytes(b"Hello, Bob!"));
320 /// assert_eq!(Ordering::Less, (*message_str).cmp("Hello, Bob!"));
321 /// ```
322 fn writeable_cmp_bytes(&self, other: &[u8]) -> core::cmp::Ordering {
323 let mut wc = cmp::WriteComparator::new(other);
324 let _ = self.write_to(&mut wc);
325 wc.finish().reverse()
326 }
327}
328
329/// Implements [`Display`](core::fmt::Display) for types that implement [`Writeable`].
330///
331/// It's recommended to do this for every [`Writeable`] type, as it will add
332/// support for `core::fmt` features like [`fmt!`](std::fmt),
333/// [`print!`](std::print), [`write!`](std::write), etc.
334#[macro_export]
335macro_rules! impl_display_with_writeable {
336 ($type:ty) => {
337 /// This trait is implemented for compatibility with [`fmt!`](alloc::fmt).
338 /// To create a string, [`Writeable::write_to_string`] is usually more efficient.
339 impl core::fmt::Display for $type {
340 #[inline]
341 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
342 $crate::Writeable::write_to(&self, f)
343 }
344 }
345 };
346}
347
348/// Testing macros for types implementing [`Writeable`].
349///
350/// Arguments, in order:
351///
352/// 1. The [`Writeable`] under test
353/// 2. The expected string value
354/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
355///
356/// Any remaining arguments get passed to `format!`
357///
358/// The macros tests the following:
359///
360/// - Equality of string content
361/// - Equality of parts ([`*_parts_eq`] only)
362/// - Validity of size hint
363/// - Reflexivity of `cmp_bytes` and order against largest and smallest strings
364///
365/// # Examples
366///
367/// ```
368/// # use writeable::Writeable;
369/// # use writeable::LengthHint;
370/// # use writeable::Part;
371/// # use writeable::assert_writeable_eq;
372/// # use writeable::assert_writeable_parts_eq;
373/// # use std::fmt::{self, Write};
374///
375/// const WORD: Part = Part {
376/// category: "foo",
377/// value: "word",
378/// };
379///
380/// struct Demo;
381/// impl Writeable for Demo {
382/// fn write_to_parts<S: writeable::PartsWrite + ?Sized>(
383/// &self,
384/// sink: &mut S,
385/// ) -> fmt::Result {
386/// sink.with_part(WORD, |w| w.write_str("foo"))
387/// }
388/// fn writeable_length_hint(&self) -> LengthHint {
389/// LengthHint::exact(3)
390/// }
391/// }
392///
393/// writeable::impl_display_with_writeable!(Demo);
394///
395/// assert_writeable_eq!(&Demo, "foo");
396/// assert_writeable_eq!(&Demo, "foo", "Message: {}", "Hello World");
397///
398/// assert_writeable_parts_eq!(&Demo, "foo", [(0, 3, WORD)]);
399/// assert_writeable_parts_eq!(
400/// &Demo,
401/// "foo",
402/// [(0, 3, WORD)],
403/// "Message: {}",
404/// "Hello World"
405/// );
406/// ```
407///
408/// [`*_parts_eq`]: assert_writeable_parts_eq
409#[macro_export]
410macro_rules! assert_writeable_eq {
411 ($actual_writeable:expr, $expected_str:expr $(,)?) => {
412 $crate::assert_writeable_eq!($actual_writeable, $expected_str, "")
413 };
414 ($actual_writeable:expr, $expected_str:expr, $($arg:tt)+) => {{
415 $crate::assert_writeable_eq!(@internal, $actual_writeable, $expected_str, $($arg)*);
416 }};
417 (@internal, $actual_writeable:expr, $expected_str:expr, $($arg:tt)+) => {{
418 let actual_writeable = &$actual_writeable;
419 let (actual_str, actual_parts) = $crate::_internal::writeable_to_parts_for_test(actual_writeable);
420 let actual_len = actual_str.len();
421 assert_eq!(actual_str, $expected_str, $($arg)*);
422 assert_eq!(actual_str, $crate::Writeable::write_to_string(actual_writeable), $($arg)+);
423 let length_hint = $crate::Writeable::writeable_length_hint(actual_writeable);
424 let lower = length_hint.0;
425 assert!(
426 lower <= actual_len,
427 "hint lower bound {lower} larger than actual length {actual_len}: {}",
428 format!($($arg)*),
429 );
430 if let Some(upper) = length_hint.1 {
431 assert!(
432 actual_len <= upper,
433 "hint upper bound {upper} smaller than actual length {actual_len}: {}",
434 format!($($arg)*),
435 );
436 }
437 assert_eq!(actual_writeable.to_string(), $expected_str);
438 let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, $expected_str.as_bytes());
439 assert_eq!(ordering, core::cmp::Ordering::Equal, $($arg)*);
440 let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, "\u{10FFFF}".as_bytes());
441 assert_eq!(ordering, core::cmp::Ordering::Less, $($arg)*);
442 if $expected_str != "" {
443 let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, "".as_bytes());
444 assert_eq!(ordering, core::cmp::Ordering::Greater, $($arg)*);
445 }
446 actual_parts // return for assert_writeable_parts_eq
447 }};
448}
449
450/// See [`assert_writeable_eq`].
451#[macro_export]
452macro_rules! assert_writeable_parts_eq {
453 ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
454 $crate::assert_writeable_parts_eq!($actual_writeable, $expected_str, $expected_parts, "")
455 };
456 ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr, $($arg:tt)+) => {{
457 let actual_parts = $crate::assert_writeable_eq!(@internal, $actual_writeable, $expected_str, $($arg)*);
458 assert_eq!(actual_parts, $expected_parts, $($arg)+);
459 }};
460}
461