writeable/
try_writeable.rs

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
5use super::*;
6use crate::parts_write_adapter::CoreWriteAsPartsWrite;
7use core::convert::Infallible;
8
9/// A writeable object that can fail while writing.
10///
11/// The default [`Writeable`] trait returns a [`fmt::Error`], which originates from the sink.
12/// In contrast, this trait allows the _writeable itself_ to trigger an error as well.
13///
14/// Implementations are expected to always make a _best attempt_ at writing to the sink
15/// and should write replacement values in the error state. Therefore, the returned `Result`
16/// can be safely ignored to emulate a "lossy" mode.
17///
18/// Any error substrings should be annotated with [`Part::ERROR`].
19///
20/// # Implementer Notes
21///
22/// This trait requires that implementers make a _best attempt_ at writing to the sink,
23/// _even in the error state_, such as with a placeholder or fallback string.
24///
25/// In [`TryWriteable::try_write_to_parts()`], error substrings should be annotated with
26/// [`Part::ERROR`]. Because of this, writing to parts is not default-implemented like
27/// it is on [`Writeable`].
28///
29/// The trait is implemented on [`Result<T, E>`] where `T` and `E` both implement [`Writeable`];
30/// In the `Ok` case, `T` is written, and in the `Err` case, `E` is written as a fallback value.
31/// This impl, which writes [`Part::ERROR`], can be used as a basis for more advanced impls.
32///
33/// # Examples
34///
35/// Implementing on a custom type:
36///
37/// ```
38/// use core::fmt;
39/// use writeable::LengthHint;
40/// use writeable::PartsWrite;
41/// use writeable::TryWriteable;
42///
43/// #[derive(Debug, PartialEq, Eq)]
44/// enum HelloWorldWriteableError {
45///     MissingName,
46/// }
47///
48/// #[derive(Debug, PartialEq, Eq)]
49/// struct HelloWorldWriteable {
50///     pub name: Option<&'static str>,
51/// }
52///
53/// impl TryWriteable for HelloWorldWriteable {
54///     type Error = HelloWorldWriteableError;
55///
56///     fn try_write_to_parts<S: PartsWrite + ?Sized>(
57///         &self,
58///         sink: &mut S,
59///     ) -> Result<Result<(), Self::Error>, fmt::Error> {
60///         sink.write_str("Hello, ")?;
61///         // Use `impl TryWriteable for Result` to generate the error part:
62///         let err = self.name.ok_or("nobody").try_write_to_parts(sink)?.err();
63///         sink.write_char('!')?;
64///         // Return a doubly-wrapped Result.
65///         // The outer Result is for fmt::Error, handled by the `?`s above.
66///         // The inner Result is for our own Self::Error.
67///         if err.is_none() {
68///             Ok(Ok(()))
69///         } else {
70///             Ok(Err(HelloWorldWriteableError::MissingName))
71///         }
72///     }
73///
74///     fn writeable_length_hint(&self) -> LengthHint {
75///         self.name.ok_or("nobody").writeable_length_hint() + 8
76///     }
77/// }
78///
79/// // Success case:
80/// writeable::assert_try_writeable_eq!(
81///     HelloWorldWriteable {
82///         name: Some("Alice")
83///     },
84///     "Hello, Alice!"
85/// );
86///
87/// // Failure case, including the ERROR part:
88/// writeable::assert_try_writeable_parts_eq!(
89///     HelloWorldWriteable { name: None },
90///     "Hello, nobody!",
91///     Err(HelloWorldWriteableError::MissingName),
92///     [(7, 13, writeable::Part::ERROR)]
93/// );
94/// ```
95pub trait TryWriteable {
96    type Error;
97
98    /// Writes the content of this writeable to a sink.
99    ///
100    /// If the sink hits an error, writing immediately ends,
101    /// `Err(`[`fmt::Error`]`)` is returned, and the sink does not contain valid output.
102    ///
103    /// If the writeable hits an error, writing is continued with a replacement value,
104    /// `Ok(Err(`[`TryWriteable::Error`]`))` is returned, and the caller may continue using the sink.
105    ///
106    /// # Lossy Mode
107    ///
108    /// The [`fmt::Error`] should always be handled, but the [`TryWriteable::Error`] can be
109    /// ignored if a fallback string is desired instead of an error.
110    ///
111    /// To handle the sink error, but not the writeable error, write:
112    ///
113    /// ```
114    /// # use writeable::TryWriteable;
115    /// # let my_writeable: Result<&str, &str> = Ok("");
116    /// # let mut sink = String::new();
117    /// let _ = my_writeable.try_write_to(&mut sink)?;
118    /// # Ok::<(), core::fmt::Error>(())
119    /// ```
120    ///
121    /// # Examples
122    ///
123    /// The following examples use `Result<&str, usize>`, which implements [`TryWriteable`] because both `&str` and `usize` do.
124    ///
125    /// Success case:
126    ///
127    /// ```
128    /// use writeable::TryWriteable;
129    ///
130    /// let w: Result<&str, usize> = Ok("success");
131    /// let mut sink = String::new();
132    /// let result = w.try_write_to(&mut sink);
133    ///
134    /// assert_eq!(result, Ok(Ok(())));
135    /// assert_eq!(sink, "success");
136    /// ```
137    ///
138    /// Failure case:
139    ///
140    /// ```
141    /// use writeable::TryWriteable;
142    ///
143    /// let w: Result<&str, usize> = Err(44);
144    /// let mut sink = String::new();
145    /// let result = w.try_write_to(&mut sink);
146    ///
147    /// assert_eq!(result, Ok(Err(44)));
148    /// assert_eq!(sink, "44");
149    /// ```
150    fn try_write_to<W: fmt::Write + ?Sized>(
151        &self,
152        sink: &mut W,
153    ) -> Result<Result<(), Self::Error>, fmt::Error> {
154        self.try_write_to_parts(&mut CoreWriteAsPartsWrite(sink))
155    }
156
157    /// Writes the content of this writeable to a sink with parts (annotations).
158    ///
159    /// For more information, see:
160    ///
161    /// - [`TryWriteable::try_write_to()`] for the general behavior.
162    /// - [`TryWriteable`] for an example with parts.
163    /// - [`Part`] for more about parts.
164    fn try_write_to_parts<S: PartsWrite + ?Sized>(
165        &self,
166        sink: &mut S,
167    ) -> Result<Result<(), Self::Error>, fmt::Error>;
168
169    /// Returns a hint for the number of UTF-8 bytes that will be written to the sink.
170    ///
171    /// This function returns the length of the "lossy mode" string; for more information,
172    /// see [`TryWriteable::try_write_to()`].
173    fn writeable_length_hint(&self) -> LengthHint {
174        LengthHint::undefined()
175    }
176
177    /// Writes the content of this writeable to a string.
178    ///
179    /// In the failure case, this function returns the error and the best-effort string ("lossy mode").
180    ///
181    /// Examples
182    ///
183    /// ```
184    /// # use std::borrow::Cow;
185    /// # use writeable::TryWriteable;
186    /// // use the best-effort string
187    /// let r1: Cow<str> = Ok::<&str, u8>("ok")
188    ///     .try_write_to_string()
189    ///     .unwrap_or_else(|(_, s)| s);
190    /// // propagate the error
191    /// let r2: Result<Cow<str>, u8> = Ok::<&str, u8>("ok")
192    ///     .try_write_to_string()
193    ///     .map_err(|(e, _)| e);
194    /// ```
195    #[cfg(feature = "alloc")]
196    fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Self::Error, Cow<'_, str>)> {
197        let hint = self.writeable_length_hint();
198        if hint.is_zero() {
199            return Ok(Cow::Borrowed(""));
200        }
201        let mut output = String::with_capacity(hint.capacity());
202        match self
203            .try_write_to(&mut output)
204            .unwrap_or_else(|fmt::Error| Ok(()))
205        {
206            Ok(()) => Ok(Cow::Owned(output)),
207            Err(e) => Err((e, Cow::Owned(output))),
208        }
209    }
210}
211
212impl<T, E> TryWriteable for Result<T, E>
213where
214    T: Writeable,
215    E: Writeable + Clone,
216{
217    type Error = E;
218
219    #[inline]
220    fn try_write_to<W: fmt::Write + ?Sized>(
221        &self,
222        sink: &mut W,
223    ) -> Result<Result<(), Self::Error>, fmt::Error> {
224        match self {
225            Ok(t) => t.write_to(sink).map(Ok),
226            Err(e) => e.write_to(sink).map(|()| Err(e.clone())),
227        }
228    }
229
230    #[inline]
231    fn try_write_to_parts<S: PartsWrite + ?Sized>(
232        &self,
233        sink: &mut S,
234    ) -> Result<Result<(), Self::Error>, fmt::Error> {
235        match self {
236            Ok(t) => t.write_to_parts(sink).map(Ok),
237            Err(e) => sink
238                .with_part(Part::ERROR, |sink| e.write_to_parts(sink))
239                .map(|()| Err(e.clone())),
240        }
241    }
242
243    #[inline]
244    fn writeable_length_hint(&self) -> LengthHint {
245        match self {
246            Ok(t) => t.writeable_length_hint(),
247            Err(e) => e.writeable_length_hint(),
248        }
249    }
250
251    #[inline]
252    #[cfg(feature = "alloc")]
253    fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Self::Error, Cow<'_, str>)> {
254        match self {
255            Ok(t) => Ok(t.write_to_string()),
256            Err(e) => Err((e.clone(), e.write_to_string())),
257        }
258    }
259}
260
261/// A wrapper around [`TryWriteable`] that implements [`Writeable`]
262/// if [`TryWriteable::Error`] is [`Infallible`].
263#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
264#[repr(transparent)]
265#[allow(clippy::exhaustive_structs)] // transparent newtype
266pub struct TryWriteableInfallibleAsWriteable<T>(pub T);
267
268impl<T> Writeable for TryWriteableInfallibleAsWriteable<T>
269where
270    T: TryWriteable<Error = Infallible>,
271{
272    #[inline]
273    fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
274        match self.0.try_write_to(sink) {
275            Ok(Ok(())) => Ok(()),
276            Ok(Err(infallible)) => match infallible {},
277            Err(e) => Err(e),
278        }
279    }
280
281    #[inline]
282    fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
283        match self.0.try_write_to_parts(sink) {
284            Ok(Ok(())) => Ok(()),
285            Ok(Err(infallible)) => match infallible {},
286            Err(e) => Err(e),
287        }
288    }
289
290    #[inline]
291    fn writeable_length_hint(&self) -> LengthHint {
292        self.0.writeable_length_hint()
293    }
294
295    #[inline]
296    #[cfg(feature = "alloc")]
297    fn write_to_string(&self) -> Cow<'_, str> {
298        match self.0.try_write_to_string() {
299            Ok(s) => s,
300            Err((infallible, _)) => match infallible {},
301        }
302    }
303}
304
305impl<T> fmt::Display for TryWriteableInfallibleAsWriteable<T>
306where
307    T: TryWriteable<Error = Infallible>,
308{
309    #[inline]
310    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
311        self.write_to(f)
312    }
313}
314
315/// A wrapper around [`Writeable`] that implements [`TryWriteable`]
316/// with [`TryWriteable::Error`] set to [`Infallible`].
317#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
318#[repr(transparent)]
319#[allow(clippy::exhaustive_structs)] // transparent newtype
320pub struct WriteableAsTryWriteableInfallible<T>(pub T);
321
322impl<T> TryWriteable for WriteableAsTryWriteableInfallible<T>
323where
324    T: Writeable,
325{
326    type Error = Infallible;
327
328    #[inline]
329    fn try_write_to<W: fmt::Write + ?Sized>(
330        &self,
331        sink: &mut W,
332    ) -> Result<Result<(), Infallible>, fmt::Error> {
333        self.0.write_to(sink).map(Ok)
334    }
335
336    #[inline]
337    fn try_write_to_parts<S: PartsWrite + ?Sized>(
338        &self,
339        sink: &mut S,
340    ) -> Result<Result<(), Infallible>, fmt::Error> {
341        self.0.write_to_parts(sink).map(Ok)
342    }
343
344    #[inline]
345    fn writeable_length_hint(&self) -> LengthHint {
346        self.0.writeable_length_hint()
347    }
348
349    #[inline]
350    #[cfg(feature = "alloc")]
351    fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Infallible, Cow<'_, str>)> {
352        Ok(self.0.write_to_string())
353    }
354}
355
356/// Testing macros for types implementing [`TryWriteable`].
357///
358/// Arguments, in order:
359///
360/// 1. The [`TryWriteable`] under test
361/// 2. The expected string value
362/// 3. The expected result value, or `Ok(())` if omitted
363/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
364///
365/// Any remaining arguments get passed to `format!`
366///
367/// The macros tests the following:
368///
369/// - Equality of string content
370/// - Equality of parts ([`*_parts_eq`] only)
371/// - Validity of size hint
372///
373/// For a usage example, see [`TryWriteable`].
374///
375/// [`*_parts_eq`]: assert_try_writeable_parts_eq
376#[macro_export]
377macro_rules! assert_try_writeable_eq {
378    ($actual_writeable:expr, $expected_str:expr $(,)?) => {
379        $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, Ok(()))
380    };
381    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr $(,)?) => {
382        $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, $expected_result, "")
383    };
384    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
385        $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
386    }};
387    (@internal, $actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
388        use $crate::TryWriteable;
389        let actual_writeable = &$actual_writeable;
390        let (actual_str, actual_parts, actual_error) = $crate::_internal::try_writeable_to_parts_for_test(actual_writeable);
391        assert_eq!(actual_str, $expected_str, $($arg)*);
392        assert_eq!(actual_error, Result::<(), _>::from($expected_result).err(), $($arg)*);
393        let actual_result = match actual_writeable.try_write_to_string() {
394            Ok(actual_cow_str) => {
395                assert_eq!(actual_cow_str, $expected_str, $($arg)+);
396                Ok(())
397            }
398            Err((e, actual_cow_str)) => {
399                assert_eq!(actual_cow_str, $expected_str, $($arg)+);
400                Err(e)
401            }
402        };
403        assert_eq!(actual_result, Result::<(), _>::from($expected_result), $($arg)*);
404        let length_hint = actual_writeable.writeable_length_hint();
405        assert!(
406            length_hint.0 <= actual_str.len(),
407            "hint lower bound {} larger than actual length {}: {}",
408            length_hint.0, actual_str.len(), format!($($arg)*),
409        );
410        if let Some(upper) = length_hint.1 {
411            assert!(
412                actual_str.len() <= upper,
413                "hint upper bound {} smaller than actual length {}: {}",
414                length_hint.0, actual_str.len(), format!($($arg)*),
415            );
416        }
417        actual_parts // return for assert_try_writeable_parts_eq
418    }};
419}
420
421/// See [`assert_try_writeable_eq`].
422#[macro_export]
423macro_rules! assert_try_writeable_parts_eq {
424    ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
425        $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, Ok(()), $expected_parts)
426    };
427    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr $(,)?) => {
428        $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, $expected_result, $expected_parts, "")
429    };
430    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr, $($arg:tt)+) => {{
431        let actual_parts = $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
432        assert_eq!(actual_parts, $expected_parts, $($arg)+);
433    }};
434}
435
436#[test]
437fn test_result_try_writeable() {
438    let mut result: Result<&str, usize> = Ok("success");
439    assert_try_writeable_eq!(result, "success");
440    result = Err(44);
441    assert_try_writeable_eq!(result, "44", Err(44));
442    assert_try_writeable_parts_eq!(result, "44", Err(44), [(0, 2, Part::ERROR)])
443}
writeable/try_writeable.rs

writeable/
try_writeable.rs
