writeable/
try_writeable.rs

Help
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    fn try_write_to_string(&self) -> Result<Cow<str>, (Self::Error, Cow<str>)> {
196        let hint = self.writeable_length_hint();
197        if hint.is_zero() {
198            return Ok(Cow::Borrowed(""));
199        }
200        let mut output = String::with_capacity(hint.capacity());
201        match self
202            .try_write_to(&mut output)
203            .unwrap_or_else(|fmt::Error| Ok(()))
204        {
205            Ok(()) => Ok(Cow::Owned(output)),
206            Err(e) => Err((e, Cow::Owned(output))),
207        }
208    }
209}
210
211impl<T, E> TryWriteable for Result<T, E>
212where
213    T: Writeable,
214    E: Writeable + Clone,
215{
216    type Error = E;
217
218    #[inline]
219    fn try_write_to<W: fmt::Write + ?Sized>(
220        &self,
221        sink: &mut W,
222    ) -> Result<Result<(), Self::Error>, fmt::Error> {
223        match self {
224            Ok(t) => t.write_to(sink).map(Ok),
225            Err(e) => e.write_to(sink).map(|()| Err(e.clone())),
226        }
227    }
228
229    #[inline]
230    fn try_write_to_parts<S: PartsWrite + ?Sized>(
231        &self,
232        sink: &mut S,
233    ) -> Result<Result<(), Self::Error>, fmt::Error> {
234        match self {
235            Ok(t) => t.write_to_parts(sink).map(Ok),
236            Err(e) => sink
237                .with_part(Part::ERROR, |sink| e.write_to_parts(sink))
238                .map(|()| Err(e.clone())),
239        }
240    }
241
242    #[inline]
243    fn writeable_length_hint(&self) -> LengthHint {
244        match self {
245            Ok(t) => t.writeable_length_hint(),
246            Err(e) => e.writeable_length_hint(),
247        }
248    }
249
250    #[inline]
251    fn try_write_to_string(&self) -> Result<Cow<str>, (Self::Error, Cow<str>)> {
252        match self {
253            Ok(t) => Ok(t.write_to_string()),
254            Err(e) => Err((e.clone(), e.write_to_string())),
255        }
256    }
257}
258
259/// A wrapper around [`TryWriteable`] that implements [`Writeable`]
260/// if [`TryWriteable::Error`] is [`Infallible`].
261#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
262#[repr(transparent)]
263#[allow(clippy::exhaustive_structs)] // transparent newtype
264pub struct TryWriteableInfallibleAsWriteable<T>(pub T);
265
266impl<T> Writeable for TryWriteableInfallibleAsWriteable<T>
267where
268    T: TryWriteable<Error = Infallible>,
269{
270    #[inline]
271    fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
272        match self.0.try_write_to(sink) {
273            Ok(Ok(())) => Ok(()),
274            Ok(Err(infallible)) => match infallible {},
275            Err(e) => Err(e),
276        }
277    }
278
279    #[inline]
280    fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
281        match self.0.try_write_to_parts(sink) {
282            Ok(Ok(())) => Ok(()),
283            Ok(Err(infallible)) => match infallible {},
284            Err(e) => Err(e),
285        }
286    }
287
288    #[inline]
289    fn writeable_length_hint(&self) -> LengthHint {
290        self.0.writeable_length_hint()
291    }
292
293    #[inline]
294    fn write_to_string(&self) -> Cow<str> {
295        match self.0.try_write_to_string() {
296            Ok(s) => s,
297            Err((infallible, _)) => match infallible {},
298        }
299    }
300}
301
302impl<T> fmt::Display for TryWriteableInfallibleAsWriteable<T>
303where
304    T: TryWriteable<Error = Infallible>,
305{
306    #[inline]
307    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
308        self.write_to(f)
309    }
310}
311
312/// A wrapper around [`Writeable`] that implements [`TryWriteable`]
313/// with [`TryWriteable::Error`] set to [`Infallible`].
314#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
315#[repr(transparent)]
316#[allow(clippy::exhaustive_structs)] // transparent newtype
317pub struct WriteableAsTryWriteableInfallible<T>(pub T);
318
319impl<T> TryWriteable for WriteableAsTryWriteableInfallible<T>
320where
321    T: Writeable,
322{
323    type Error = Infallible;
324
325    #[inline]
326    fn try_write_to<W: fmt::Write + ?Sized>(
327        &self,
328        sink: &mut W,
329    ) -> Result<Result<(), Infallible>, fmt::Error> {
330        self.0.write_to(sink).map(Ok)
331    }
332
333    #[inline]
334    fn try_write_to_parts<S: PartsWrite + ?Sized>(
335        &self,
336        sink: &mut S,
337    ) -> Result<Result<(), Infallible>, fmt::Error> {
338        self.0.write_to_parts(sink).map(Ok)
339    }
340
341    #[inline]
342    fn writeable_length_hint(&self) -> LengthHint {
343        self.0.writeable_length_hint()
344    }
345
346    #[inline]
347    fn try_write_to_string(&self) -> Result<Cow<str>, (Infallible, Cow<str>)> {
348        Ok(self.0.write_to_string())
349    }
350}
351
352/// Testing macros for types implementing [`TryWriteable`].
353///
354/// Arguments, in order:
355///
356/// 1. The [`TryWriteable`] under test
357/// 2. The expected string value
358/// 3. The expected result value, or `Ok(())` if omitted
359/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
360///
361/// Any remaining arguments get passed to `format!`
362///
363/// The macros tests the following:
364///
365/// - Equality of string content
366/// - Equality of parts ([`*_parts_eq`] only)
367/// - Validity of size hint
368///
369/// For a usage example, see [`TryWriteable`].
370///
371/// [`*_parts_eq`]: assert_try_writeable_parts_eq
372#[macro_export]
373macro_rules! assert_try_writeable_eq {
374    ($actual_writeable:expr, $expected_str:expr $(,)?) => {
375        $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, Ok(()))
376    };
377    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr $(,)?) => {
378        $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, $expected_result, "")
379    };
380    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
381        $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
382    }};
383    (@internal, $actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
384        use $crate::TryWriteable;
385        let actual_writeable = &$actual_writeable;
386        let (actual_str, actual_parts, actual_error) = $crate::_internal::try_writeable_to_parts_for_test(actual_writeable);
387        assert_eq!(actual_str, $expected_str, $($arg)*);
388        assert_eq!(actual_error, Result::<(), _>::from($expected_result).err(), $($arg)*);
389        let actual_result = match actual_writeable.try_write_to_string() {
390            Ok(actual_cow_str) => {
391                assert_eq!(actual_cow_str, $expected_str, $($arg)+);
392                Ok(())
393            }
394            Err((e, actual_cow_str)) => {
395                assert_eq!(actual_cow_str, $expected_str, $($arg)+);
396                Err(e)
397            }
398        };
399        assert_eq!(actual_result, Result::<(), _>::from($expected_result), $($arg)*);
400        let length_hint = actual_writeable.writeable_length_hint();
401        assert!(
402            length_hint.0 <= actual_str.len(),
403            "hint lower bound {} larger than actual length {}: {}",
404            length_hint.0, actual_str.len(), format!($($arg)*),
405        );
406        if let Some(upper) = length_hint.1 {
407            assert!(
408                actual_str.len() <= upper,
409                "hint upper bound {} smaller than actual length {}: {}",
410                length_hint.0, actual_str.len(), format!($($arg)*),
411            );
412        }
413        actual_parts // return for assert_try_writeable_parts_eq
414    }};
415}
416
417/// See [`assert_try_writeable_eq`].
418#[macro_export]
419macro_rules! assert_try_writeable_parts_eq {
420    ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
421        $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, Ok(()), $expected_parts)
422    };
423    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr $(,)?) => {
424        $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, $expected_result, $expected_parts, "")
425    };
426    ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr, $($arg:tt)+) => {{
427        let actual_parts = $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
428        assert_eq!(actual_parts, $expected_parts, $($arg)+);
429    }};
430}
431
432#[test]
433fn test_result_try_writeable() {
434    let mut result: Result<&str, usize> = Ok("success");
435    assert_try_writeable_eq!(result, "success");
436    result = Err(44);
437    assert_try_writeable_eq!(result, "44", Err(44));
438    assert_try_writeable_parts_eq!(result, "44", Err(44), [(0, 2, Part::ERROR)])
439}
writeable/try_writeable.rs

writeable/
try_writeable.rs
