diff options
Diffstat (limited to 'vendor/writeable/src/try_writeable.rs')
| -rw-r--r-- | vendor/writeable/src/try_writeable.rs | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/vendor/writeable/src/try_writeable.rs b/vendor/writeable/src/try_writeable.rs new file mode 100644 index 00000000..aa918bbd --- /dev/null +++ b/vendor/writeable/src/try_writeable.rs @@ -0,0 +1,439 @@ +// 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 ). + +use super::*; +use crate::parts_write_adapter::CoreWriteAsPartsWrite; +use core::convert::Infallible; + +/// A writeable object that can fail while writing. +/// +/// The default [`Writeable`] trait returns a [`fmt::Error`], which originates from the sink. +/// In contrast, this trait allows the _writeable itself_ to trigger an error as well. +/// +/// Implementations are expected to always make a _best attempt_ at writing to the sink +/// and should write replacement values in the error state. Therefore, the returned `Result` +/// can be safely ignored to emulate a "lossy" mode. +/// +/// Any error substrings should be annotated with [`Part::ERROR`]. +/// +/// # Implementer Notes +/// +/// This trait requires that implementers make a _best attempt_ at writing to the sink, +/// _even in the error state_, such as with a placeholder or fallback string. +/// +/// In [`TryWriteable::try_write_to_parts()`], error substrings should be annotated with +/// [`Part::ERROR`]. Because of this, writing to parts is not default-implemented like +/// it is on [`Writeable`]. +/// +/// The trait is implemented on [`Result<T, E>`] where `T` and `E` both implement [`Writeable`]; +/// In the `Ok` case, `T` is written, and in the `Err` case, `E` is written as a fallback value. +/// This impl, which writes [`Part::ERROR`], can be used as a basis for more advanced impls. +/// +/// # Examples +/// +/// Implementing on a custom type: +/// +/// ``` +/// use core::fmt; +/// use writeable::LengthHint; +/// use writeable::PartsWrite; +/// use writeable::TryWriteable; +/// +/// #[derive(Debug, PartialEq, Eq)] +/// enum HelloWorldWriteableError { +/// MissingName, +/// } +/// +/// #[derive(Debug, PartialEq, Eq)] +/// struct HelloWorldWriteable { +/// pub name: Option<&'static str>, +/// } +/// +/// impl TryWriteable for HelloWorldWriteable { +/// type Error = HelloWorldWriteableError; +/// +/// fn try_write_to_parts<S: PartsWrite + ?Sized>( +/// &self, +/// sink: &mut S, +/// ) -> Result<Result<(), Self::Error>, fmt::Error> { +/// sink.write_str("Hello, ")?; +/// // Use `impl TryWriteable for Result` to generate the error part: +/// let err = self.name.ok_or("nobody").try_write_to_parts(sink)?.err(); +/// sink.write_char('!')?; +/// // Return a doubly-wrapped Result. +/// // The outer Result is for fmt::Error, handled by the `?`s above. +/// // The inner Result is for our own Self::Error. +/// if err.is_none() { +/// Ok(Ok(())) +/// } else { +/// Ok(Err(HelloWorldWriteableError::MissingName)) +/// } +/// } +/// +/// fn writeable_length_hint(&self) -> LengthHint { +/// self.name.ok_or("nobody").writeable_length_hint() + 8 +/// } +/// } +/// +/// // Success case: +/// writeable::assert_try_writeable_eq!( +/// HelloWorldWriteable { +/// name: Some("Alice") +/// }, +/// "Hello, Alice!" +/// ); +/// +/// // Failure case, including the ERROR part: +/// writeable::assert_try_writeable_parts_eq!( +/// HelloWorldWriteable { name: None }, +/// "Hello, nobody!", +/// Err(HelloWorldWriteableError::MissingName), +/// [(7, 13, writeable::Part::ERROR)] +/// ); +/// ``` +pub trait TryWriteable { + type Error; + + /// Writes the content of this writeable to a sink. + /// + /// If the sink hits an error, writing immediately ends, + /// `Err(`[`fmt::Error`]`)` is returned, and the sink does not contain valid output. + /// + /// If the writeable hits an error, writing is continued with a replacement value, + /// `Ok(Err(`[`TryWriteable::Error`]`))` is returned, and the caller may continue using the sink. + /// + /// # Lossy Mode + /// + /// The [`fmt::Error`] should always be handled, but the [`TryWriteable::Error`] can be + /// ignored if a fallback string is desired instead of an error. + /// + /// To handle the sink error, but not the writeable error, write: + /// + /// ``` + /// # use writeable::TryWriteable; + /// # let my_writeable: Result<&str, &str> = Ok(""); + /// # let mut sink = String::new(); + /// let _ = my_writeable.try_write_to(&mut sink)?; + /// # Ok::<(), core::fmt::Error>(()) + /// ``` + /// + /// # Examples + /// + /// The following examples use `Result<&str, usize>`, which implements [`TryWriteable`] because both `&str` and `usize` do. + /// + /// Success case: + /// + /// ``` + /// use writeable::TryWriteable; + /// + /// let w: Result<&str, usize> = Ok("success"); + /// let mut sink = String::new(); + /// let result = w.try_write_to(&mut sink); + /// + /// assert_eq!(result, Ok(Ok(()))); + /// assert_eq!(sink, "success"); + /// ``` + /// + /// Failure case: + /// + /// ``` + /// use writeable::TryWriteable; + /// + /// let w: Result<&str, usize> = Err(44); + /// let mut sink = String::new(); + /// let result = w.try_write_to(&mut sink); + /// + /// assert_eq!(result, Ok(Err(44))); + /// assert_eq!(sink, "44"); + /// ``` + fn try_write_to<W: fmt::Write + ?Sized>( + &self, + sink: &mut W, + ) -> Result<Result<(), Self::Error>, fmt::Error> { + self.try_write_to_parts(&mut CoreWriteAsPartsWrite(sink)) + } + + /// Writes the content of this writeable to a sink with parts (annotations). + /// + /// For more information, see: + /// + /// - [`TryWriteable::try_write_to()`] for the general behavior. + /// - [`TryWriteable`] for an example with parts. + /// - [`Part`] for more about parts. + fn try_write_to_parts<S: PartsWrite + ?Sized>( + &self, + sink: &mut S, + ) -> Result<Result<(), Self::Error>, fmt::Error>; + + /// Returns a hint for the number of UTF-8 bytes that will be written to the sink. + /// + /// This function returns the length of the "lossy mode" string; for more information, + /// see [`TryWriteable::try_write_to()`]. + fn writeable_length_hint(&self) -> LengthHint { + LengthHint::undefined() + } + + /// Writes the content of this writeable to a string. + /// + /// In the failure case, this function returns the error and the best-effort string ("lossy mode"). + /// + /// Examples + /// + /// ``` + /// # use std::borrow::Cow; + /// # use writeable::TryWriteable; + /// // use the best-effort string + /// let r1: Cow<str> = Ok::<&str, u8>("ok") + /// .try_write_to_string() + /// .unwrap_or_else(|(_, s)| s); + /// // propagate the error + /// let r2: Result<Cow<str>, u8> = Ok::<&str, u8>("ok") + /// .try_write_to_string() + /// .map_err(|(e, _)| e); + /// ``` + fn try_write_to_string(&self) -> Result<Cow<str>, (Self::Error, Cow<str>)> { + let hint = self.writeable_length_hint(); + if hint.is_zero() { + return Ok(Cow::Borrowed("")); + } + let mut output = String::with_capacity(hint.capacity()); + match self + .try_write_to(&mut output) + .unwrap_or_else(|fmt::Error| Ok(())) + { + Ok(()) => Ok(Cow::Owned(output)), + Err(e) => Err((e, Cow::Owned(output))), + } + } +} + +impl<T, E> TryWriteable for Result<T, E> +where + T: Writeable, + E: Writeable + Clone, +{ + type Error = E; + + #[inline] + fn try_write_to<W: fmt::Write + ?Sized>( + &self, + sink: &mut W, + ) -> Result<Result<(), Self::Error>, fmt::Error> { + match self { + Ok(t) => t.write_to(sink).map(Ok), + Err(e) => e.write_to(sink).map(|()| Err(e.clone())), + } + } + + #[inline] + fn try_write_to_parts<S: PartsWrite + ?Sized>( + &self, + sink: &mut S, + ) -> Result<Result<(), Self::Error>, fmt::Error> { + match self { + Ok(t) => t.write_to_parts(sink).map(Ok), + Err(e) => sink + .with_part(Part::ERROR, |sink| e.write_to_parts(sink)) + .map(|()| Err(e.clone())), + } + } + + #[inline] + fn writeable_length_hint(&self) -> LengthHint { + match self { + Ok(t) => t.writeable_length_hint(), + Err(e) => e.writeable_length_hint(), + } + } + + #[inline] + fn try_write_to_string(&self) -> Result<Cow<str>, (Self::Error, Cow<str>)> { + match self { + Ok(t) => Ok(t.write_to_string()), + Err(e) => Err((e.clone(), e.write_to_string())), + } + } +} + +/// A wrapper around [`TryWriteable`] that implements [`Writeable`] +/// if [`TryWriteable::Error`] is [`Infallible`]. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[repr(transparent)] +#[allow(clippy::exhaustive_structs)] // transparent newtype +pub struct TryWriteableInfallibleAsWriteable<T>(pub T); + +impl<T> Writeable for TryWriteableInfallibleAsWriteable<T> +where + T: TryWriteable<Error = Infallible>, +{ + #[inline] + fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result { + match self.0.try_write_to(sink) { + Ok(Ok(())) => Ok(()), + Ok(Err(infallible)) => match infallible {}, + Err(e) => Err(e), + } + } + + #[inline] + fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result { + match self.0.try_write_to_parts(sink) { + Ok(Ok(())) => Ok(()), + Ok(Err(infallible)) => match infallible {}, + Err(e) => Err(e), + } + } + + #[inline] + fn writeable_length_hint(&self) -> LengthHint { + self.0.writeable_length_hint() + } + + #[inline] + fn write_to_string(&self) -> Cow<str> { + match self.0.try_write_to_string() { + Ok(s) => s, + Err((infallible, _)) => match infallible {}, + } + } +} + +impl<T> fmt::Display for TryWriteableInfallibleAsWriteable<T> +where + T: TryWriteable<Error = Infallible>, +{ + #[inline] + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.write_to(f) + } +} + +/// A wrapper around [`Writeable`] that implements [`TryWriteable`] +/// with [`TryWriteable::Error`] set to [`Infallible`]. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[repr(transparent)] +#[allow(clippy::exhaustive_structs)] // transparent newtype +pub struct WriteableAsTryWriteableInfallible<T>(pub T); + +impl<T> TryWriteable for WriteableAsTryWriteableInfallible<T> +where + T: Writeable, +{ + type Error = Infallible; + + #[inline] + fn try_write_to<W: fmt::Write + ?Sized>( + &self, + sink: &mut W, + ) -> Result<Result<(), Infallible>, fmt::Error> { + self.0.write_to(sink).map(Ok) + } + + #[inline] + fn try_write_to_parts<S: PartsWrite + ?Sized>( + &self, + sink: &mut S, + ) -> Result<Result<(), Infallible>, fmt::Error> { + self.0.write_to_parts(sink).map(Ok) + } + + #[inline] + fn writeable_length_hint(&self) -> LengthHint { + self.0.writeable_length_hint() + } + + #[inline] + fn try_write_to_string(&self) -> Result<Cow<str>, (Infallible, Cow<str>)> { + Ok(self.0.write_to_string()) + } +} + +/// Testing macros for types implementing [`TryWriteable`]. +/// +/// Arguments, in order: +/// +/// 1. The [`TryWriteable`] under test +/// 2. The expected string value +/// 3. The expected result value, or `Ok(())` if omitted +/// 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 +/// +/// For a usage example, see [`TryWriteable`]. +/// +/// [`*_parts_eq`]: assert_try_writeable_parts_eq +#[macro_export] +macro_rules! assert_try_writeable_eq { + ($actual_writeable:expr, $expected_str:expr $(,)?) => { + $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, Ok(())) + }; + ($actual_writeable:expr, $expected_str:expr, $expected_result:expr $(,)?) => { + $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, $expected_result, "") + }; + ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{ + $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*); + }}; + (@internal, $actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{ + use $crate::TryWriteable; + let actual_writeable = &$actual_writeable; + let (actual_str, actual_parts, actual_error) = $crate::_internal::try_writeable_to_parts_for_test(actual_writeable); + assert_eq!(actual_str, $expected_str, $($arg)*); + assert_eq!(actual_error, Result::<(), _>::from($expected_result).err(), $($arg)*); + let actual_result = match actual_writeable.try_write_to_string() { + Ok(actual_cow_str) => { + assert_eq!(actual_cow_str, $expected_str, $($arg)+); + Ok(()) + } + Err((e, actual_cow_str)) => { + assert_eq!(actual_cow_str, $expected_str, $($arg)+); + Err(e) + } + }; + assert_eq!(actual_result, Result::<(), _>::from($expected_result), $($arg)*); + let length_hint = actual_writeable.writeable_length_hint(); + assert!( + length_hint.0 <= actual_str.len(), + "hint lower bound {} larger than actual length {}: {}", + length_hint.0, actual_str.len(), format!($($arg)*), + ); + if let Some(upper) = length_hint.1 { + assert!( + actual_str.len() <= upper, + "hint upper bound {} smaller than actual length {}: {}", + length_hint.0, actual_str.len(), format!($($arg)*), + ); + } + actual_parts // return for assert_try_writeable_parts_eq + }}; +} + +/// See [`assert_try_writeable_eq`]. +#[macro_export] +macro_rules! assert_try_writeable_parts_eq { + ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => { + $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, Ok(()), $expected_parts) + }; + ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr $(,)?) => { + $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, $expected_result, $expected_parts, "") + }; + ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr, $($arg:tt)+) => {{ + let actual_parts = $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*); + assert_eq!(actual_parts, $expected_parts, $($arg)+); + }}; +} + +#[test] +fn test_result_try_writeable() { + let mut result: Result<&str, usize> = Ok("success"); + assert_try_writeable_eq!(result, "success"); + result = Err(44); + assert_try_writeable_eq!(result, "44", Err(44)); + assert_try_writeable_parts_eq!(result, "44", Err(44), [(0, 2, Part::ERROR)]) +} |