| // 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)]) |
| } |