summaryrefslogtreecommitdiffstats
path: root/vendor/writeable/src/lib.rs
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/writeable/src/lib.rs')
-rw-r--r--vendor/writeable/src/lib.rs390
1 files changed, 390 insertions, 0 deletions
diff --git a/vendor/writeable/src/lib.rs b/vendor/writeable/src/lib.rs
new file mode 100644
index 000000000..66be7f33b
--- /dev/null
+++ b/vendor/writeable/src/lib.rs
@@ -0,0 +1,390 @@
+// 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/docs/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 impls;
+mod ops;
+
+use alloc::borrow::Cow;
+use alloc::string::String;
+use alloc::vec::Vec;
+use core::fmt;
+
+/// 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)
+ }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+#[allow(clippy::exhaustive_structs)] // stable
+pub struct Part {
+ pub category: &'static str,
+ pub value: &'static str,
+}
+
+/// 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 {
+ struct CoreWriteAsPartsWrite<W: fmt::Write + ?Sized>(W);
+ impl<W: fmt::Write + ?Sized> fmt::Write for CoreWriteAsPartsWrite<W> {
+ fn write_str(&mut self, s: &str) -> fmt::Result {
+ self.0.write_str(s)
+ }
+
+ fn write_char(&mut self, c: char) -> fmt::Result {
+ self.0.write_char(c)
+ }
+ }
+
+ impl<W: fmt::Write + ?Sized> PartsWrite for CoreWriteAsPartsWrite<W> {
+ type SubPartsWrite = CoreWriteAsPartsWrite<W>;
+
+ fn with_part(
+ &mut self,
+ _part: Part,
+ mut f: impl FnMut(&mut Self::SubPartsWrite) -> fmt::Result,
+ ) -> fmt::Result {
+ f(self)
+ }
+ }
+
+ self.write_to_parts(&mut 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 mut output = String::with_capacity(self.writeable_length_hint().capacity());
+ let _ = self.write_to(&mut output);
+ Cow::Owned(output)
+ }
+}
+
+/// 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. The first argument should be a
+/// `Writeable`, the second argument a string, and the third argument (*_parts_eq only)
+/// a list of parts (`[(usize, usize, Part)]`).
+///
+/// The macros tests for equality of string content, parts (*_parts_eq only), and
+/// verify the size hint.
+///
+/// # 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");
+/// ```
+#[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)+) => {{
+ let actual_writeable = &$actual_writeable;
+ let (actual_str, _) = $crate::writeable_to_parts_for_test(actual_writeable).unwrap();
+ 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);
+ assert!(length_hint.0 <= actual_str.len(), $($arg)*);
+ if let Some(upper) = length_hint.1 {
+ assert!(actual_str.len() <= upper, $($arg)*);
+ }
+ }};
+}
+
+/// 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_writeable = &$actual_writeable;
+ let (actual_str, actual_parts) = $crate::writeable_to_parts_for_test(actual_writeable).unwrap();
+ assert_eq!(actual_str, $expected_str, $($arg)+);
+ assert_eq!(actual_str, $crate::Writeable::write_to_string(actual_writeable), $($arg)+);
+ assert_eq!(actual_parts, $expected_parts, $($arg)+);
+ let length_hint = $crate::Writeable::writeable_length_hint(actual_writeable);
+ assert!(length_hint.0 <= actual_str.len(), $($arg)+);
+ if let Some(upper) = length_hint.1 {
+ assert!(actual_str.len() <= upper, $($arg)+);
+ }
+ }};
+}
+
+#[doc(hidden)]
+#[allow(clippy::type_complexity)]
+pub fn writeable_to_parts_for_test<W: Writeable>(
+ writeable: &W,
+) -> Result<(String, Vec<(usize, usize, Part)>), fmt::Error> {
+ struct State {
+ string: alloc::string::String,
+ parts: Vec<(usize, usize, Part)>,
+ }
+
+ impl fmt::Write for State {
+ fn write_str(&mut self, s: &str) -> fmt::Result {
+ self.string.write_str(s)
+ }
+ fn write_char(&mut self, c: char) -> fmt::Result {
+ self.string.write_char(c)
+ }
+ }
+
+ impl PartsWrite for State {
+ type SubPartsWrite = Self;
+ fn with_part(
+ &mut self,
+ part: Part,
+ mut f: impl FnMut(&mut Self::SubPartsWrite) -> fmt::Result,
+ ) -> fmt::Result {
+ let start = self.string.len();
+ f(self)?;
+ self.parts.push((start, self.string.len(), part));
+ Ok(())
+ }
+ }
+
+ let mut state = State {
+ string: alloc::string::String::new(),
+ parts: Vec::new(),
+ };
+ writeable.write_to_parts(&mut state)?;
+
+ // Sort by first open and last closed
+ state
+ .parts
+ .sort_unstable_by_key(|(begin, end, _)| (*begin, end.wrapping_neg()));
+ Ok((state.string, state.parts))
+}