/rust/registry/src/index.crates.io-6f17d22bba15001f/writeable-0.5.5/src/lib.rs

Source (jump to first uncovered line)
// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).

// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
#![cfg_attr(all(not(test), not(doc)), no_std)]
#![cfg_attr(
    not(test),
    deny(
        clippy::indexing_slicing,
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::exhaustive_structs,
        clippy::exhaustive_enums,
        missing_debug_implementations,
    )
)]

//! `writeable` is a utility crate of the [`ICU4X`] project.
//!
//! It includes [`Writeable`], a core trait representing an object that can be written to a
//! sink implementing `std::fmt::Write`. It is an alternative to `std::fmt::Display` with the
//! addition of a function indicating the number of bytes to be written.
//!
//! `Writeable` improves upon `std::fmt::Display` in two ways:
//!
//! 1. More efficient, since the sink can pre-allocate bytes.
//! 2. Smaller code, since the format machinery can be short-circuited.
//!
//! # Examples
//!
//! ```
//! use std::fmt;
//! use writeable::assert_writeable_eq;
//! use writeable::LengthHint;
//! use writeable::Writeable;
//!
//! struct WelcomeMessage<'s> {
//!     pub name: &'s str,
//! }
//!
//! impl<'s> Writeable for WelcomeMessage<'s> {
//!     fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
//!         sink.write_str("Hello, ")?;
//!         sink.write_str(self.name)?;
//!         sink.write_char('!')?;
//!         Ok(())
//!     }
//!
//!     fn writeable_length_hint(&self) -> LengthHint {
//!         // "Hello, " + '!' + length of name
//!         LengthHint::exact(8 + self.name.len())
//!     }
//! }
//!
//! let message = WelcomeMessage { name: "Alice" };
//! assert_writeable_eq!(&message, "Hello, Alice!");
//!
//! // Types implementing `Writeable` are recommended to also implement `fmt::Display`.
//! // This can be simply done by redirecting to the `Writeable` implementation:
//! writeable::impl_display_with_writeable!(WelcomeMessage<'_>);
//! ```
//!
//! [`ICU4X`]: ../icu/index.html

extern crate alloc;

mod cmp;
#[cfg(feature = "either")]
mod either;
mod impls;
mod ops;
mod parts_write_adapter;
mod testing;
mod try_writeable;

use alloc::borrow::Cow;
use alloc::string::String;
use core::fmt;

pub use try_writeable::TryWriteable;

/// Helper types for trait impls.
pub mod adapters {
    use super::*;

    pub use parts_write_adapter::CoreWriteAsPartsWrite;
    pub use try_writeable::TryWriteableInfallibleAsWriteable;
    pub use try_writeable::WriteableAsTryWriteableInfallible;
}

#[doc(hidden)]
pub mod _internal {
    pub use super::testing::try_writeable_to_parts_for_test;
    pub use super::testing::writeable_to_parts_for_test;
}

/// A hint to help consumers of `Writeable` pre-allocate bytes before they call
/// [`write_to`](Writeable::write_to).
///
/// This behaves like `Iterator::size_hint`: it is a tuple where the first element is the
/// lower bound, and the second element is the upper bound. If the upper bound is `None`
/// either there is no known upper bound, or the upper bound is larger than `usize`.
///
/// `LengthHint` implements std`::ops::{Add, Mul}` and similar traits for easy composition.
/// During computation, the lower bound will saturate at `usize::MAX`, while the upper
/// bound will become `None` if `usize::MAX` is exceeded.
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
#[non_exhaustive]
pub struct LengthHint(pub usize, pub Option<usize>);

impl LengthHint {
    pub fn undefined() -> Self {
        Self(0, None)
    }

    /// `write_to` will use exactly n bytes.
    pub fn exact(n: usize) -> Self {
        Self(n, Some(n))
    }

    /// `write_to` will use at least n bytes.
    pub fn at_least(n: usize) -> Self {
        Self(n, None)
    }

    /// `write_to` will use at most n bytes.
    pub fn at_most(n: usize) -> Self {
        Self(0, Some(n))
    }

    /// `write_to` will use between `n` and `m` bytes.
    pub fn between(n: usize, m: usize) -> Self {
        Self(Ord::min(n, m), Some(Ord::max(n, m)))
    }

    /// Returns a recommendation for the number of bytes to pre-allocate.
    /// If an upper bound exists, this is used, otherwise the lower bound
    /// (which might be 0).
    ///
    /// # Examples
    ///
    /// ```
    /// use writeable::Writeable;
    ///
    /// fn pre_allocate_string(w: &impl Writeable) -> String {
    ///     String::with_capacity(w.writeable_length_hint().capacity())
    /// }
    /// ```
    pub fn capacity(&self) -> usize {
        self.1.unwrap_or(self.0)
    }

    /// Returns whether the `LengthHint` indicates that the string is exactly 0 bytes long.
    pub fn is_zero(&self) -> bool {
        self.1 == Some(0)
    }
}

/// [`Part`]s are used as annotations for formatted strings. For example, a string like
/// `Alice, Bob` could assign a `NAME` part to the substrings `Alice` and `Bob`, and a
/// `PUNCTUATION` part to `, `. This allows for example to apply styling only to names.
///
/// `Part` contains two fields, whose usage is left up to the producer of the [`Writeable`].
/// Conventionally, the `category` field will identify the formatting logic that produces
/// the string/parts, whereas the `value` field will have semantic meaning. `NAME` and
/// `PUNCTUATION` could thus be defined as
/// ```
/// # use writeable::Part;
/// const NAME: Part = Part {
///     category: "userlist",
///     value: "name",
/// };
/// const PUNCTUATION: Part = Part {
///     category: "userlist",
///     value: "punctuation",
/// };
/// ```
///
/// That said, consumers should not usually have to inspect `Part` internals. Instead,
/// formatters should expose the `Part`s they produces as constants.
#[derive(Clone, Copy, Debug, PartialEq)]
#[allow(clippy::exhaustive_structs)] // stable
pub struct Part {
    pub category: &'static str,
    pub value: &'static str,
}

impl Part {
    /// A part that should annotate error segments in [`TryWriteable`] output.
    ///
    /// For an example, see [`TryWriteable`].
    pub const ERROR: Part = Part {
        category: "writeable",
        value: "error",
    };
}

/// A sink that supports annotating parts of the string with `Part`s.
pub trait PartsWrite: fmt::Write {
    type SubPartsWrite: PartsWrite + ?Sized;

    fn with_part(
        &mut self,
        part: Part,
        f: impl FnMut(&mut Self::SubPartsWrite) -> fmt::Result,
    ) -> fmt::Result;
}

/// `Writeable` is an alternative to `std::fmt::Display` with the addition of a length function.
pub trait Writeable {
    /// Writes a string to the given sink. Errors from the sink are bubbled up.
    /// The default implementation delegates to `write_to_parts`, and discards any
    /// `Part` annotations.
    fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
        self.write_to_parts(&mut parts_write_adapter::CoreWriteAsPartsWrite(sink))
    }

    /// Write bytes and `Part` annotations to the given sink. Errors from the
    /// sink are bubbled up. The default implementation delegates to `write_to`,
    /// and doesn't produce any `Part` annotations.
    fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
        self.write_to(sink)
    }

    /// Returns a hint for the number of UTF-8 bytes that will be written to the sink.
    ///
    /// Override this method if it can be computed quickly.
    fn writeable_length_hint(&self) -> LengthHint {
        LengthHint::undefined()
    }

    /// Creates a new `String` with the data from this `Writeable`. Like `ToString`,
    /// but smaller and faster.
    ///
    /// The default impl allocates an owned `String`. However, if it is possible to return a
    /// borrowed string, overwrite this method to return a `Cow::Borrowed`.
    ///
    /// To remove the `Cow` wrapper, call `.into_owned()` or `.as_str()` as appropriate.
    ///
    /// # Examples
    ///
    /// Inspect a `Writeable` before writing it to the sink:
    ///
    /// ```
    /// use core::fmt::{Result, Write};
    /// use writeable::Writeable;
    ///
    /// fn write_if_ascii<W, S>(w: &W, sink: &mut S) -> Result
    /// where
    ///     W: Writeable + ?Sized,
    ///     S: Write + ?Sized,
    /// {
    ///     let s = w.write_to_string();
    ///     if s.is_ascii() {
    ///         sink.write_str(&s)
    ///     } else {
    ///         Ok(())
    ///     }
    /// }
    /// ```
    ///
    /// Convert the `Writeable` into a fully owned `String`:
    ///
    /// ```
    /// use writeable::Writeable;
    ///
    /// fn make_string(w: &impl Writeable) -> String {
    ///     w.write_to_string().into_owned()
    /// }
    /// ```
    fn write_to_string(&self) -> Cow<str> {
        let hint = self.writeable_length_hint();
        if hint.is_zero() {
            return Cow::Borrowed("");
        }
        let mut output = String::with_capacity(hint.capacity());
        let _ = self.write_to(&mut output);
        Cow::Owned(output)
    }

    /// Compares the contents of this `Writeable` to the given bytes
    /// without allocating a String to hold the `Writeable` contents.
    ///
    /// This returns a lexicographical comparison, the same as if the Writeable
    /// were first converted to a String and then compared with `Ord`. For a
    /// locale-sensitive string ordering, use an ICU4X Collator.
    ///
    /// # Examples
    ///
    /// ```
    /// use core::cmp::Ordering;
    /// use core::fmt;
    /// use writeable::Writeable;
    ///
    /// struct WelcomeMessage<'s> {
    ///     pub name: &'s str,
    /// }
    ///
    /// impl<'s> Writeable for WelcomeMessage<'s> {
    ///     // see impl in Writeable docs
    /// #    fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
    /// #        sink.write_str("Hello, ")?;
    /// #        sink.write_str(self.name)?;
    /// #        sink.write_char('!')?;
    /// #        Ok(())
    /// #    }
    /// }
    ///
    /// let message = WelcomeMessage { name: "Alice" };
    /// let message_str = message.write_to_string();
    ///
    /// assert_eq!(Ordering::Equal, message.writeable_cmp_bytes(b"Hello, Alice!"));
    ///
    /// assert_eq!(Ordering::Greater, message.writeable_cmp_bytes(b"Alice!"));
    /// assert_eq!(Ordering::Greater, (*message_str).cmp("Alice!"));
    ///
    /// assert_eq!(Ordering::Less, message.writeable_cmp_bytes(b"Hello, Bob!"));
    /// assert_eq!(Ordering::Less, (*message_str).cmp("Hello, Bob!"));
    /// ```
    fn writeable_cmp_bytes(&self, other: &[u8]) -> core::cmp::Ordering {
        let mut wc = cmp::WriteComparator::new(other);
        let _ = self.write_to(&mut wc);
        wc.finish().reverse()
    }
}

/// Implements [`Display`](core::fmt::Display) for types that implement [`Writeable`].
///
/// It's recommended to do this for every [`Writeable`] type, as it will add
/// support for `core::fmt` features like [`fmt!`](std::fmt),
/// [`print!`](std::print), [`write!`](std::write), etc.
#[macro_export]
macro_rules! impl_display_with_writeable {
    ($type:ty) => {
        /// This trait is implemented for compatibility with [`fmt!`](alloc::fmt).
        /// To create a string, [`Writeable::write_to_string`] is usually more efficient.
        impl core::fmt::Display for $type {
            #[inline]
            fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
                $crate::Writeable::write_to(&self, f)
            }
        }
    };
}

/// Testing macros for types implementing [`Writeable`].
///
/// Arguments, in order:
///
/// 1. The [`Writeable`] under test
/// 2. The expected string value
/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
///
/// Any remaining arguments get passed to `format!`
///
/// The macros tests the following:
///
/// - Equality of string content
/// - Equality of parts ([`*_parts_eq`] only)
/// - Validity of size hint
/// - Reflexivity of `cmp_bytes` and order against largest and smallest strings
///
/// # Examples
///
/// ```
/// # use writeable::Writeable;
/// # use writeable::LengthHint;
/// # use writeable::Part;
/// # use writeable::assert_writeable_eq;
/// # use writeable::assert_writeable_parts_eq;
/// # use std::fmt::{self, Write};
///
/// const WORD: Part = Part {
///     category: "foo",
///     value: "word",
/// };
///
/// struct Demo;
/// impl Writeable for Demo {
///     fn write_to_parts<S: writeable::PartsWrite + ?Sized>(
///         &self,
///         sink: &mut S,
///     ) -> fmt::Result {
///         sink.with_part(WORD, |w| w.write_str("foo"))
///     }
///     fn writeable_length_hint(&self) -> LengthHint {
///         LengthHint::exact(3)
///     }
/// }
///
/// writeable::impl_display_with_writeable!(Demo);
///
/// assert_writeable_eq!(&Demo, "foo");
/// assert_writeable_eq!(&Demo, "foo", "Message: {}", "Hello World");
///
/// assert_writeable_parts_eq!(&Demo, "foo", [(0, 3, WORD)]);
/// assert_writeable_parts_eq!(
///     &Demo,
///     "foo",
///     [(0, 3, WORD)],
///     "Message: {}",
///     "Hello World"
/// );
/// ```
///
/// [`*_parts_eq`]: assert_writeable_parts_eq
#[macro_export]
macro_rules! assert_writeable_eq {
    ($actual_writeable:expr, $expected_str:expr $(,)?) => {
        $crate::assert_writeable_eq!($actual_writeable, $expected_str, "")
    };
    ($actual_writeable:expr, $expected_str:expr, $($arg:tt)+) => {{
        $crate::assert_writeable_eq!(@internal, $actual_writeable, $expected_str, $($arg)*);
    }};
    (@internal, $actual_writeable:expr, $expected_str:expr, $($arg:tt)+) => {{
        let actual_writeable = &$actual_writeable;
        let (actual_str, actual_parts) = $crate::_internal::writeable_to_parts_for_test(actual_writeable);
        let actual_len = actual_str.len();
        assert_eq!(actual_str, $expected_str, $($arg)*);
        assert_eq!(actual_str, $crate::Writeable::write_to_string(actual_writeable), $($arg)+);
        let length_hint = $crate::Writeable::writeable_length_hint(actual_writeable);
        let lower = length_hint.0;
        assert!(
            lower <= actual_len,
            "hint lower bound {lower} larger than actual length {actual_len}: {}",
            format!($($arg)*),
        );
        if let Some(upper) = length_hint.1 {
            assert!(
                actual_len <= upper,
                "hint upper bound {upper} smaller than actual length {actual_len}: {}",
                format!($($arg)*),
            );
        }
        assert_eq!(actual_writeable.to_string(), $expected_str);
        let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, $expected_str.as_bytes());
        assert_eq!(ordering, core::cmp::Ordering::Equal, $($arg)*);
        let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, "\u{10FFFF}".as_bytes());
        assert_eq!(ordering, core::cmp::Ordering::Less, $($arg)*);
        if $expected_str != "" {
            let ordering = $crate::Writeable::writeable_cmp_bytes(actual_writeable, "".as_bytes());
            assert_eq!(ordering, core::cmp::Ordering::Greater, $($arg)*);
        }
        actual_parts // return for assert_writeable_parts_eq
    }};
}

/// See [`assert_writeable_eq`].
#[macro_export]
macro_rules! assert_writeable_parts_eq {
    ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
        $crate::assert_writeable_parts_eq!($actual_writeable, $expected_str, $expected_parts, "")
    };
    ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr, $($arg:tt)+) => {{
        let actual_parts = $crate::assert_writeable_eq!(@internal, $actual_writeable, $expected_str, $($arg)*);
        assert_eq!(actual_parts, $expected_parts, $($arg)+);
    }};
}

Coverage Report

Created: 2025-05-08 06:26

Line	Count	Source (jump to first uncovered line)
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
67		extern crate alloc;
68
69		mod cmp;
70		#[cfg(feature = "either")]
71		mod either;
72		mod impls;
73		mod ops;
74		mod parts_write_adapter;
75		mod testing;
76		mod try_writeable;
77
78		use alloc::borrow::Cow;
79		use alloc::string::String;
80		use core::fmt;
81
82		pub use try_writeable::TryWriteable;
83
84		/// Helper types for trait impls.
85		pub 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)]
94		pub 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]
111		pub struct LengthHint(pub usize, pub Option<usize>);
112
113		impl LengthHint {
114	0	pub fn undefined() -> Self {
115	0	Self(0, None)
116	0	}
117
118		/// `write_to` will use exactly n bytes.
119	0	pub fn exact(n: usize) -> Self {
120	0	Self(n, Some(n))
121	0	}
122
123		/// `write_to` will use at least n bytes.
124	0	pub fn at_least(n: usize) -> Self {
125	0	Self(n, None)
126	0	}
127
128		/// `write_to` will use at most n bytes.
129	0	pub fn at_most(n: usize) -> Self {
130	0	Self(0, Some(n))
131	0	}
132
133		/// `write_to` will use between `n` and `m` bytes.
134	0	pub fn between(n: usize, m: usize) -> Self {
135	0	Self(Ord::min(n, m), Some(Ord::max(n, m)))
136	0	}
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	0	pub fn capacity(&self) -> usize {
152	0	self.1.unwrap_or(self.0)
153	0	}
154
155		/// Returns whether the `LengthHint` indicates that the string is exactly 0 bytes long.
156	0	pub fn is_zero(&self) -> bool {
157	0	self.1 == Some(0)
158	0	}
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
185		pub struct Part {
186		pub category: &'static str,
187		pub value: &'static str,
188		}
189
190		impl 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.
201		pub 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.
212		pub 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	0	fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
217	0	self.write_to_parts(&mut parts_write_adapter::CoreWriteAsPartsWrite(sink))
218	0	}
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	0	fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
224	0	self.write_to(sink)
225	0	}
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	0	fn writeable_length_hint(&self) -> LengthHint {
231	0	LengthHint::undefined()
232	0	}
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	0	fn write_to_string(&self) -> Cow<str> {
274	0	let hint = self.writeable_length_hint();
275	0	if hint.is_zero() {
276	0	return Cow::Borrowed("");
277	0	}
278	0	let mut output = String::with_capacity(hint.capacity());
279	0	let _ = self.write_to(&mut output);
280	0	Cow::Owned(output)
281	0	}
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	0	fn writeable_cmp_bytes(&self, other: &[u8]) -> core::cmp::Ordering {
323	0	let mut wc = cmp::WriteComparator::new(other);
324	0	let _ = self.write_to(&mut wc);
325	0	wc.finish().reverse()
326	0	} Unexecuted instantiation: <icu_provider::request::DataLocale as writeable::Writeable>::writeable_cmp_bytes Unexecuted instantiation: <icu_locid::langid::LanguageIdentifier as writeable::Writeable>::writeable_cmp_bytes Unexecuted instantiation: <icu_locid::extensions::unicode::keywords::Keywords as writeable::Writeable>::writeable_cmp_bytes Unexecuted instantiation: <icu_locid::locale::Locale as writeable::Writeable>::writeable_cmp_bytes Unexecuted instantiation: <_ as writeable::Writeable>::writeable_cmp_bytes
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]
335		macro_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	0	fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
342	0	$crate::Writeable::write_to(&self, f)
343	0	} Unexecuted instantiation: <icu_provider::key::DataKey as core::fmt::Display>::fmt Unexecuted instantiation: <icu_provider::request::DataLocale as core::fmt::Display>::fmt Unexecuted instantiation: <icu_provider::hello_world::FormattedHelloWorld as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::langid::LanguageIdentifier as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::locale::Locale as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::other::subtag::Subtag as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::other::Other as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::private::other::Subtag as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::private::Private as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::transform::fields::Fields as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::transform::key::Key as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::transform::value::Value as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::transform::Transform as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::attribute::Attribute as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::attributes::Attributes as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::key::Key as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::keywords::Keywords as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::value::Value as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::unicode::Unicode as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::extensions::Extensions as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::subtags::language::Language as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::subtags::region::Region as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::subtags::script::Script as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::subtags::variant::Variant as core::fmt::Display>::fmt Unexecuted instantiation: <icu_locid::subtags::variants::Variants as core::fmt::Display>::fmt
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]
410		macro_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]
452		macro_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		}