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::{cmp::Ordering, 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 /// Compares the content of this writeable to a byte slice.
211 ///
212 /// This function compares the "lossy mode" string; for more information,
213 /// see [`TryWriteable::try_write_to()`].
214 ///
215 /// For more information, see [`Writeable::writeable_cmp_bytes()`].
216 ///
217 /// # Examples
218 ///
219 /// ```
220 /// use core::cmp::Ordering;
221 /// use core::fmt;
222 /// use writeable::TryWriteable;
223 /// # use writeable::PartsWrite;
224 /// # use writeable::LengthHint;
225 ///
226 /// #[derive(Debug, PartialEq, Eq)]
227 /// enum HelloWorldWriteableError {
228 /// MissingName
229 /// }
230 ///
231 /// #[derive(Debug, PartialEq, Eq)]
232 /// struct HelloWorldWriteable {
233 /// pub name: Option<&'static str>
234 /// }
235 ///
236 /// impl TryWriteable for HelloWorldWriteable {
237 /// type Error = HelloWorldWriteableError;
238 /// // see impl in TryWriteable docs
239 /// # fn try_write_to_parts<S: PartsWrite + ?Sized>(
240 /// # &self,
241 /// # sink: &mut S,
242 /// # ) -> Result<Result<(), Self::Error>, fmt::Error> {
243 /// # sink.write_str("Hello, ")?;
244 /// # // Use `impl TryWriteable for Result` to generate the error part:
245 /// # let _ = self.name.ok_or("nobody").try_write_to_parts(sink)?;
246 /// # sink.write_char('!')?;
247 /// # // Return a doubly-wrapped Result.
248 /// # // The outer Result is for fmt::Error, handled by the `?`s above.
249 /// # // The inner Result is for our own Self::Error.
250 /// # if self.name.is_some() {
251 /// # Ok(Ok(()))
252 /// # } else {
253 /// # Ok(Err(HelloWorldWriteableError::MissingName))
254 /// # }
255 /// # }
256 /// }
257 ///
258 /// // Success case:
259 /// let writeable = HelloWorldWriteable { name: Some("Alice") };
260 /// let writeable_str = writeable.try_write_to_string().expect("name is Some");
261 ///
262 /// assert_eq!(Ordering::Equal, writeable.writeable_cmp_bytes(b"Hello, Alice!"));
263 ///
264 /// assert_eq!(Ordering::Greater, writeable.writeable_cmp_bytes(b"Alice!"));
265 /// assert_eq!(Ordering::Greater, (*writeable_str).cmp("Alice!"));
266 ///
267 /// assert_eq!(Ordering::Less, writeable.writeable_cmp_bytes(b"Hello, Bob!"));
268 /// assert_eq!(Ordering::Less, (*writeable_str).cmp("Hello, Bob!"));
269 ///
270 /// // Failure case:
271 /// let writeable = HelloWorldWriteable { name: None };
272 /// let mut writeable_str = String::new();
273 /// let _ = writeable.try_write_to(&mut writeable_str).expect("write to String is infallible");
274 ///
275 /// assert_eq!(Ordering::Equal, writeable.writeable_cmp_bytes(b"Hello, nobody!"));
276 ///
277 /// assert_eq!(Ordering::Greater, writeable.writeable_cmp_bytes(b"Hello, alice!"));
278 /// assert_eq!(Ordering::Greater, (*writeable_str).cmp("Hello, alice!"));
279 ///
280 /// assert_eq!(Ordering::Less, writeable.writeable_cmp_bytes(b"Hello, zero!"));
281 /// assert_eq!(Ordering::Less, (*writeable_str).cmp("Hello, zero!"));
282 /// ```
283 fn writeable_cmp_bytes(&self, other: &[u8]) -> Ordering {
284 let mut wc = cmp::WriteComparator::new(other);
285 let _ = self
286 .try_write_to(&mut wc)
287 .unwrap_or_else(|fmt::Error| Ok(()));
288 wc.finish().reverse()
289 }
290}
291
292impl<T, E> TryWriteable for Result<T, E>
293where
294 T: Writeable,
295 E: Writeable + Clone,
296{
297 type Error = E;
298
299 #[inline]
300 fn try_write_to<W: fmt::Write + ?Sized>(
301 &self,
302 sink: &mut W,
303 ) -> Result<Result<(), Self::Error>, fmt::Error> {
304 match self {
305 Ok(t) => t.write_to(sink).map(Ok),
306 Err(e) => e.write_to(sink).map(|()| Err(e.clone())),
307 }
308 }
309
310 #[inline]
311 fn try_write_to_parts<S: PartsWrite + ?Sized>(
312 &self,
313 sink: &mut S,
314 ) -> Result<Result<(), Self::Error>, fmt::Error> {
315 match self {
316 Ok(t) => t.write_to_parts(sink).map(Ok),
317 Err(e) => sink
318 .with_part(Part::ERROR, |sink| e.write_to_parts(sink))
319 .map(|()| Err(e.clone())),
320 }
321 }
322
323 #[inline]
324 fn writeable_length_hint(&self) -> LengthHint {
325 match self {
326 Ok(t) => t.writeable_length_hint(),
327 Err(e) => e.writeable_length_hint(),
328 }
329 }
330
331 #[inline]
332 fn try_write_to_string(&self) -> Result<Cow<str>, (Self::Error, Cow<str>)> {
333 match self {
334 Ok(t) => Ok(t.write_to_string()),
335 Err(e) => Err((e.clone(), e.write_to_string())),
336 }
337 }
338
339 #[inline]
340 fn writeable_cmp_bytes(&self, other: &[u8]) -> Ordering {
341 match self {
342 Ok(t) => t.writeable_cmp_bytes(other),
343 Err(e) => e.writeable_cmp_bytes(other),
344 }
345 }
346}
347
348/// A wrapper around [`TryWriteable`] that implements [`Writeable`]
349/// if [`TryWriteable::Error`] is [`Infallible`].
350#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
351#[repr(transparent)]
352#[allow(clippy::exhaustive_structs)] // transparent newtype
353pub struct TryWriteableInfallibleAsWriteable<T>(pub T);
354
355impl<T> Writeable for TryWriteableInfallibleAsWriteable<T>
356where
357 T: TryWriteable<Error = Infallible>,
358{
359 #[inline]
360 fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
361 match self.0.try_write_to(sink) {
362 Ok(Ok(())) => Ok(()),
363 Ok(Err(infallible)) => match infallible {},
364 Err(e) => Err(e),
365 }
366 }
367
368 #[inline]
369 fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
370 match self.0.try_write_to_parts(sink) {
371 Ok(Ok(())) => Ok(()),
372 Ok(Err(infallible)) => match infallible {},
373 Err(e) => Err(e),
374 }
375 }
376
377 #[inline]
378 fn writeable_length_hint(&self) -> LengthHint {
379 self.0.writeable_length_hint()
380 }
381
382 #[inline]
383 fn write_to_string(&self) -> Cow<str> {
384 match self.0.try_write_to_string() {
385 Ok(s) => s,
386 Err((infallible, _)) => match infallible {},
387 }
388 }
389
390 #[inline]
391 fn writeable_cmp_bytes(&self, other: &[u8]) -> core::cmp::Ordering {
392 self.0.writeable_cmp_bytes(other)
393 }
394}
395
396impl<T> fmt::Display for TryWriteableInfallibleAsWriteable<T>
397where
398 T: TryWriteable<Error = Infallible>,
399{
400 #[inline]
401 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
402 self.write_to(sink:f)
403 }
404}
405
406/// A wrapper around [`Writeable`] that implements [`TryWriteable`]
407/// with [`TryWriteable::Error`] set to [`Infallible`].
408#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
409#[repr(transparent)]
410#[allow(clippy::exhaustive_structs)] // transparent newtype
411pub struct WriteableAsTryWriteableInfallible<T>(pub T);
412
413impl<T> TryWriteable for WriteableAsTryWriteableInfallible<T>
414where
415 T: Writeable,
416{
417 type Error = Infallible;
418
419 #[inline]
420 fn try_write_to<W: fmt::Write + ?Sized>(
421 &self,
422 sink: &mut W,
423 ) -> Result<Result<(), Infallible>, fmt::Error> {
424 self.0.write_to(sink).map(Ok)
425 }
426
427 #[inline]
428 fn try_write_to_parts<S: PartsWrite + ?Sized>(
429 &self,
430 sink: &mut S,
431 ) -> Result<Result<(), Infallible>, fmt::Error> {
432 self.0.write_to_parts(sink).map(Ok)
433 }
434
435 #[inline]
436 fn writeable_length_hint(&self) -> LengthHint {
437 self.0.writeable_length_hint()
438 }
439
440 #[inline]
441 fn try_write_to_string(&self) -> Result<Cow<str>, (Infallible, Cow<str>)> {
442 Ok(self.0.write_to_string())
443 }
444
445 #[inline]
446 fn writeable_cmp_bytes(&self, other: &[u8]) -> core::cmp::Ordering {
447 self.0.writeable_cmp_bytes(other)
448 }
449}
450
451/// Testing macros for types implementing [`TryWriteable`].
452///
453/// Arguments, in order:
454///
455/// 1. The [`TryWriteable`] under test
456/// 2. The expected string value
457/// 3. The expected result value, or `Ok(())` if omitted
458/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
459///
460/// Any remaining arguments get passed to `format!`
461///
462/// The macros tests the following:
463///
464/// - Equality of string content
465/// - Equality of parts ([`*_parts_eq`] only)
466/// - Validity of size hint
467/// - Reflexivity of `cmp_bytes` and order against largest and smallest strings
468///
469/// For a usage example, see [`TryWriteable`].
470///
471/// [`*_parts_eq`]: assert_try_writeable_parts_eq
472#[macro_export]
473macro_rules! assert_try_writeable_eq {
474 ($actual_writeable:expr, $expected_str:expr $(,)?) => {
475 $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, Ok(()))
476 };
477 ($actual_writeable:expr, $expected_str:expr, $expected_result:expr $(,)?) => {
478 $crate::assert_try_writeable_eq!($actual_writeable, $expected_str, $expected_result, "")
479 };
480 ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
481 $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
482 }};
483 (@internal, $actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
484 use $crate::TryWriteable;
485 let actual_writeable = &$actual_writeable;
486 let (actual_str, actual_parts, actual_error) = $crate::_internal::try_writeable_to_parts_for_test(actual_writeable);
487 assert_eq!(actual_str, $expected_str, $($arg)*);
488 assert_eq!(actual_error, Result::<(), _>::from($expected_result).err(), $($arg)*);
489 let actual_result = match actual_writeable.try_write_to_string() {
490 Ok(actual_cow_str) => {
491 assert_eq!(actual_cow_str, $expected_str, $($arg)+);
492 Ok(())
493 }
494 Err((e, actual_cow_str)) => {
495 assert_eq!(actual_cow_str, $expected_str, $($arg)+);
496 Err(e)
497 }
498 };
499 assert_eq!(actual_result, Result::<(), _>::from($expected_result), $($arg)*);
500 let length_hint = actual_writeable.writeable_length_hint();
501 assert!(
502 length_hint.0 <= actual_str.len(),
503 "hint lower bound {} larger than actual length {}: {}",
504 length_hint.0, actual_str.len(), format!($($arg)*),
505 );
506 if let Some(upper) = length_hint.1 {
507 assert!(
508 actual_str.len() <= upper,
509 "hint upper bound {} smaller than actual length {}: {}",
510 length_hint.0, actual_str.len(), format!($($arg)*),
511 );
512 }
513 let ordering = actual_writeable.writeable_cmp_bytes($expected_str.as_bytes());
514 assert_eq!(ordering, core::cmp::Ordering::Equal, $($arg)*);
515 let ordering = actual_writeable.writeable_cmp_bytes("\u{10FFFF}".as_bytes());
516 assert_eq!(ordering, core::cmp::Ordering::Less, $($arg)*);
517 if $expected_str != "" {
518 let ordering = actual_writeable.writeable_cmp_bytes("".as_bytes());
519 assert_eq!(ordering, core::cmp::Ordering::Greater, $($arg)*);
520 }
521 actual_parts // return for assert_try_writeable_parts_eq
522 }};
523}
524
525/// See [`assert_try_writeable_eq`].
526#[macro_export]
527macro_rules! assert_try_writeable_parts_eq {
528 ($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
529 $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, Ok(()), $expected_parts)
530 };
531 ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr $(,)?) => {
532 $crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, $expected_result, $expected_parts, "")
533 };
534 ($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr, $($arg:tt)+) => {{
535 let actual_parts = $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
536 assert_eq!(actual_parts, $expected_parts, $($arg)+);
537 }};
538}
539
540#[test]
541fn test_result_try_writeable() {
542 let mut result: Result<&str, usize> = Ok("success");
543 assert_try_writeable_eq!(result, "success");
544 result = Err(44);
545 assert_try_writeable_eq!(result, "44", Err(44));
546 assert_try_writeable_parts_eq!(result, "44", Err(44), [(0, 2, Part::ERROR)])
547}
548