515 lines
17 KiB
Rust
515 lines
17 KiB
Rust
// 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(not(any(test, doc)), no_std)]
|
|
#![cfg_attr(
|
|
not(test),
|
|
deny(
|
|
clippy::indexing_slicing,
|
|
clippy::unwrap_used,
|
|
clippy::expect_used,
|
|
clippy::panic,
|
|
)
|
|
)]
|
|
#![warn(missing_docs)]
|
|
|
|
//! This crate defines [`Writeable`], a 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.
|
|
//!
|
|
//! This crate also exports [`TryWriteable`], a writeable that supports a custom error.
|
|
//!
|
|
//! # Benchmarks
|
|
//!
|
|
//! The benchmarks to generate the following data can be found in the `benches` directory.
|
|
//!
|
|
//! | Case | `Writeable` | `Display` |
|
|
//! |---|---|---|
|
|
//! | Create string from single-string message (139 chars) | 15.642 ns | 19.251 ns |
|
|
//! | Create string from complex message | 35.830 ns | 89.478 ns |
|
|
//! | Write complex message to buffer | 57.336 ns | 64.408 ns |
|
|
//!
|
|
//! # 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<'_>);
|
|
//! assert_eq!(message.to_string(), "Hello, Alice!");
|
|
//! ```
|
|
//!
|
|
//! [`ICU4X`]: ../icu/index.html
|
|
|
|
#[cfg(feature = "alloc")]
|
|
extern crate alloc;
|
|
|
|
mod cmp;
|
|
mod concat;
|
|
#[cfg(feature = "either")]
|
|
mod either;
|
|
mod impls;
|
|
mod ops;
|
|
mod parts_write_adapter;
|
|
#[cfg(feature = "alloc")]
|
|
mod testing;
|
|
#[cfg(feature = "alloc")]
|
|
mod to_string_or_borrow;
|
|
mod try_writeable;
|
|
|
|
#[cfg(feature = "alloc")]
|
|
use alloc::borrow::Cow;
|
|
|
|
#[cfg(feature = "alloc")]
|
|
use alloc::string::String;
|
|
use core::fmt;
|
|
|
|
pub use cmp::{cmp_str, cmp_utf8};
|
|
pub use concat::concat_writeable;
|
|
#[cfg(feature = "alloc")]
|
|
pub use to_string_or_borrow::to_string_or_borrow;
|
|
pub use try_writeable::TryWriteable;
|
|
|
|
/// Helper types for trait impls.
|
|
pub mod adapters {
|
|
use super::*;
|
|
|
|
pub use concat::Concat;
|
|
pub use parts_write_adapter::CoreWriteAsPartsWrite;
|
|
pub use parts_write_adapter::WithPart;
|
|
pub use try_writeable::TryWriteableInfallibleAsWriteable;
|
|
pub use try_writeable::WriteableAsTryWriteableInfallible;
|
|
|
|
/// A lossy wrapper for a [`TryWriteable`] that implements [`Writeable`]
|
|
/// and ignores any errors.
|
|
#[derive(Debug)]
|
|
#[allow(clippy::exhaustive_structs)] // newtype
|
|
pub struct LossyWrap<T>(pub T);
|
|
|
|
impl<T: TryWriteable> Writeable for LossyWrap<T> {
|
|
fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
|
|
let _ = self.0.try_write_to(sink)?;
|
|
Ok(())
|
|
}
|
|
|
|
fn writeable_length_hint(&self) -> LengthHint {
|
|
self.0.writeable_length_hint()
|
|
}
|
|
}
|
|
|
|
impl<T: TryWriteable> fmt::Display for LossyWrap<T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
let _ = self.0.try_write_to(f)?;
|
|
Ok(())
|
|
}
|
|
}
|
|
}
|
|
|
|
#[doc(hidden)] // for testing and macros
|
|
pub mod _internal {
|
|
#[cfg(feature = "alloc")]
|
|
pub use super::testing::try_writeable_to_parts_for_test;
|
|
#[cfg(feature = "alloc")]
|
|
pub use super::testing::writeable_to_parts_for_test;
|
|
#[cfg(feature = "alloc")]
|
|
pub use alloc::string::String;
|
|
}
|
|
|
|
/// 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 {
|
|
/// Unknown
|
|
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
|
|
#[allow(missing_docs)] // behavior not defined, explained in type docs
|
|
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 {
|
|
/// The recursive sink
|
|
type SubPartsWrite: PartsWrite + ?Sized;
|
|
|
|
/// Annotates all strings written by the closure with the given [`Part`].
|
|
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()
|
|
}
|
|
|
|
/// Returns a `&str` that matches the output of `write_to`, if possible.
|
|
///
|
|
/// This method is used to avoid materializing a [`String`] in `write_to_string`.
|
|
fn writeable_borrow(&self) -> Option<&str> {
|
|
None
|
|
}
|
|
|
|
/// Creates a new string with the data from this `Writeable`.
|
|
///
|
|
/// Unlike [`to_string`](ToString::to_string), this does not pull in `core::fmt`
|
|
/// code, and borrows the string if possible.
|
|
///
|
|
/// 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()
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// # Note to implementors
|
|
///
|
|
/// This method has a default implementation in terms of `writeable_borrow`,
|
|
/// `writeable_length_hint`, and `write_to`. The only case
|
|
/// where this should be implemented is if the computation of `writeable_borrow`
|
|
/// requires a full invocation of `write_to`. In this case, implement this
|
|
/// using [`to_string_or_borrow`].
|
|
///
|
|
/// # `alloc` Cargo feature
|
|
///
|
|
/// Calling or implementing this method requires the `alloc` Cargo feature.
|
|
/// However, as all the methods required by the default implementation do
|
|
/// not require the `alloc` Cargo feature, a caller that uses the feature
|
|
/// can still call this on types from crates that don't use the `alloc`
|
|
/// Cargo feature.
|
|
#[cfg(feature = "alloc")]
|
|
fn write_to_string(&self) -> Cow<'_, str> {
|
|
if let Some(borrow) = self.writeable_borrow() {
|
|
return Cow::Borrowed(borrow);
|
|
}
|
|
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)
|
|
}
|
|
}
|
|
|
|
/// 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.
|
|
///
|
|
/// This macro also adds a concrete `to_string` function. This function will shadow the
|
|
/// standard library `ToString`, using the more efficient writeable-based code path.
|
|
/// To add only `Display`, use the `@display` macro variant.
|
|
#[macro_export]
|
|
macro_rules! impl_display_with_writeable {
|
|
(@display, $type:ty) => {
|
|
/// This trait is implemented for compatibility with [`fmt!`](core::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)
|
|
}
|
|
}
|
|
};
|
|
($type:ty $(, #[$alloc_feature:meta])? ) => {
|
|
$crate::impl_display_with_writeable!(@display, $type);
|
|
$(#[$alloc_feature])?
|
|
impl $type {
|
|
/// Converts the given value to a `String`.
|
|
///
|
|
/// Under the hood, this uses an efficient [`Writeable`] implementation.
|
|
/// However, in order to avoid allocating a string, it is more efficient
|
|
/// to use [`Writeable`] directly.
|
|
pub fn to_string(&self) -> $crate::_internal::String {
|
|
$crate::Writeable::write_to_string(self).into_owned()
|
|
}
|
|
}
|
|
};
|
|
}
|
|
|
|
/// 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
|
|
///
|
|
/// # 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]
|
|
#[cfg(feature = "alloc")]
|
|
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)*);
|
|
let cow = $crate::Writeable::write_to_string(actual_writeable);
|
|
assert_eq!(actual_str, cow, $($arg)+);
|
|
if let Some(borrowed) = ($crate::Writeable::writeable_borrow(&actual_writeable)) {
|
|
assert_eq!(borrowed, $expected_str, $($arg)*);
|
|
assert!(matches!(cow, std::borrow::Cow::Borrowed(_)), $($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, $($arg)*);
|
|
actual_parts // return for assert_writeable_parts_eq
|
|
}};
|
|
}
|
|
|
|
/// See [`assert_writeable_eq`].
|
|
#[macro_export]
|
|
#[cfg(feature = "alloc")]
|
|
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)+);
|
|
}};
|
|
}
|