/rust/registry/src/index.crates.io-1949cf8c6b5b557f/writeable-0.6.3/src/try_writeable.rs

Source
// 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 {
    /// The error type
    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);
    /// ```
    #[cfg(feature = "alloc")]
    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]
    #[cfg(feature = "alloc")]
    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]
    #[cfg(feature = "alloc")]
    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]
    #[cfg(feature = "alloc")]
    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)])
}

Coverage Report

Created: 2026-06-30 07:02

Line	Count	Source
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
5		use super::*;
6		use crate::parts_write_adapter::CoreWriteAsPartsWrite;
7		use 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		/// ```
95		pub trait TryWriteable {
96		/// The error type
97		type Error;
98
99		/// Writes the content of this writeable to a sink.
100		///
101		/// If the sink hits an error, writing immediately ends,
102		/// `Err(`[`fmt::Error`]`)` is returned, and the sink does not contain valid output.
103		///
104		/// If the writeable hits an error, writing is continued with a replacement value,
105		/// `Ok(Err(`[`TryWriteable::Error`]`))` is returned, and the caller may continue using the sink.
106		///
107		/// # Lossy Mode
108		///
109		/// The [`fmt::Error`] should always be handled, but the [`TryWriteable::Error`] can be
110		/// ignored if a fallback string is desired instead of an error.
111		///
112		/// To handle the sink error, but not the writeable error, write:
113		///
114		/// ```
115		/// # use writeable::TryWriteable;
116		/// # let my_writeable: Result<&str, &str> = Ok("");
117		/// # let mut sink = String::new();
118		/// let _ = my_writeable.try_write_to(&mut sink)?;
119		/// # Ok::<(), core::fmt::Error>(())
120		/// ```
121		///
122		/// # Examples
123		///
124		/// The following examples use `Result<&str, usize>`, which implements [`TryWriteable`] because both `&str` and `usize` do.
125		///
126		/// Success case:
127		///
128		/// ```
129		/// use writeable::TryWriteable;
130		///
131		/// let w: Result<&str, usize> = Ok("success");
132		/// let mut sink = String::new();
133		/// let result = w.try_write_to(&mut sink);
134		///
135		/// assert_eq!(result, Ok(Ok(())));
136		/// assert_eq!(sink, "success");
137		/// ```
138		///
139		/// Failure case:
140		///
141		/// ```
142		/// use writeable::TryWriteable;
143		///
144		/// let w: Result<&str, usize> = Err(44);
145		/// let mut sink = String::new();
146		/// let result = w.try_write_to(&mut sink);
147		///
148		/// assert_eq!(result, Ok(Err(44)));
149		/// assert_eq!(sink, "44");
150		/// ```
151	0	fn try_write_to<W: fmt::Write + ?Sized>(
152	0	&self,
153	0	sink: &mut W,
154	0	) -> Result<Result<(), Self::Error>, fmt::Error> {
155	0	self.try_write_to_parts(&mut CoreWriteAsPartsWrite(sink))
156	0	}
157
158		/// Writes the content of this writeable to a sink with parts (annotations).
159		///
160		/// For more information, see:
161		///
162		/// - [`TryWriteable::try_write_to()`] for the general behavior.
163		/// - [`TryWriteable`] for an example with parts.
164		/// - [`Part`] for more about parts.
165		fn try_write_to_parts<S: PartsWrite + ?Sized>(
166		&self,
167		sink: &mut S,
168		) -> Result<Result<(), Self::Error>, fmt::Error>;
169
170		/// Returns a hint for the number of UTF-8 bytes that will be written to the sink.
171		///
172		/// This function returns the length of the "lossy mode" string; for more information,
173		/// see [`TryWriteable::try_write_to()`].
174	0	fn writeable_length_hint(&self) -> LengthHint {
175	0	LengthHint::undefined()
176	0	}
177
178		/// Writes the content of this writeable to a string.
179		///
180		/// In the failure case, this function returns the error and the best-effort string ("lossy mode").
181		///
182		/// Examples
183		///
184		/// ```
185		/// # use std::borrow::Cow;
186		/// # use writeable::TryWriteable;
187		/// // use the best-effort string
188		/// let r1: Cow<str> = Ok::<&str, u8>("ok")
189		/// .try_write_to_string()
190		/// .unwrap_or_else(\|(_, s)\| s);
191		/// // propagate the error
192		/// let r2: Result<Cow<str>, u8> = Ok::<&str, u8>("ok")
193		/// .try_write_to_string()
194		/// .map_err(\|(e, _)\| e);
195		/// ```
196		#[cfg(feature = "alloc")]
197		fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Self::Error, Cow<'_, str>)> {
198		let hint = self.writeable_length_hint();
199		if hint.is_zero() {
200		return Ok(Cow::Borrowed(""));
201		}
202		let mut output = String::with_capacity(hint.capacity());
203		match self
204		.try_write_to(&mut output)
205		.unwrap_or_else(\|fmt::Error\| Ok(()))
206		{
207		Ok(()) => Ok(Cow::Owned(output)),
208		Err(e) => Err((e, Cow::Owned(output))),
209		}
210		}
211		}
212
213		impl<T, E> TryWriteable for Result<T, E>
214		where
215		T: Writeable,
216		E: Writeable + Clone,
217		{
218		type Error = E;
219
220		#[inline]
221	0	fn try_write_to<W: fmt::Write + ?Sized>(
222	0	&self,
223	0	sink: &mut W,
224	0	) -> Result<Result<(), Self::Error>, fmt::Error> {
225	0	match self {
226	0	Ok(t) => t.write_to(sink).map(Ok),
227	0	Err(e) => e.write_to(sink).map(\|()\| Err(e.clone())),
228		}
229	0	}
230
231		#[inline]
232	0	fn try_write_to_parts<S: PartsWrite + ?Sized>(
233	0	&self,
234	0	sink: &mut S,
235	0	) -> Result<Result<(), Self::Error>, fmt::Error> {
236	0	match self {
237	0	Ok(t) => t.write_to_parts(sink).map(Ok),
238	0	Err(e) => sink
239	0	.with_part(Part::ERROR, \|sink\| e.write_to_parts(sink))
240	0	.map(\|()\| Err(e.clone())),
241		}
242	0	}
243
244		#[inline]
245	0	fn writeable_length_hint(&self) -> LengthHint {
246	0	match self {
247	0	Ok(t) => t.writeable_length_hint(),
248	0	Err(e) => e.writeable_length_hint(),
249		}
250	0	}
251
252		#[inline]
253		#[cfg(feature = "alloc")]
254		fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Self::Error, Cow<'_, str>)> {
255		match self {
256		Ok(t) => Ok(t.write_to_string()),
257		Err(e) => Err((e.clone(), e.write_to_string())),
258		}
259		}
260		}
261
262		/// A wrapper around [`TryWriteable`] that implements [`Writeable`]
263		/// if [`TryWriteable::Error`] is [`Infallible`].
264		#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
265		#[repr(transparent)]
266		#[allow(clippy::exhaustive_structs)] // transparent newtype
267		pub struct TryWriteableInfallibleAsWriteable<T>(pub T);
268
269		impl<T> Writeable for TryWriteableInfallibleAsWriteable<T>
270		where
271		T: TryWriteable<Error = Infallible>,
272		{
273		#[inline]
274	0	fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
275	0	match self.0.try_write_to(sink) {
276	0	Ok(Ok(())) => Ok(()),
277		Ok(Err(infallible)) => match infallible {},
278	0	Err(e) => Err(e),
279		}
280	0	}
281
282		#[inline]
283	0	fn write_to_parts<S: PartsWrite + ?Sized>(&self, sink: &mut S) -> fmt::Result {
284	0	match self.0.try_write_to_parts(sink) {
285	0	Ok(Ok(())) => Ok(()),
286		Ok(Err(infallible)) => match infallible {},
287	0	Err(e) => Err(e),
288		}
289	0	}
290
291		#[inline]
292	0	fn writeable_length_hint(&self) -> LengthHint {
293	0	self.0.writeable_length_hint()
294	0	}
295
296		#[inline]
297		#[cfg(feature = "alloc")]
298		fn write_to_string(&self) -> Cow<'_, str> {
299		match self.0.try_write_to_string() {
300		Ok(s) => s,
301		Err((infallible, _)) => match infallible {},
302		}
303		}
304		}
305
306		impl<T> fmt::Display for TryWriteableInfallibleAsWriteable<T>
307		where
308		T: TryWriteable<Error = Infallible>,
309		{
310		#[inline]
311	0	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
312	0	self.write_to(f)
313	0	}
314		}
315
316		/// A wrapper around [`Writeable`] that implements [`TryWriteable`]
317		/// with [`TryWriteable::Error`] set to [`Infallible`].
318		#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
319		#[repr(transparent)]
320		#[allow(clippy::exhaustive_structs)] // transparent newtype
321		pub struct WriteableAsTryWriteableInfallible<T>(pub T);
322
323		impl<T> TryWriteable for WriteableAsTryWriteableInfallible<T>
324		where
325		T: Writeable,
326		{
327		type Error = Infallible;
328
329		#[inline]
330	0	fn try_write_to<W: fmt::Write + ?Sized>(
331	0	&self,
332	0	sink: &mut W,
333	0	) -> Result<Result<(), Infallible>, fmt::Error> {
334	0	self.0.write_to(sink).map(Ok)
335	0	}
336
337		#[inline]
338	0	fn try_write_to_parts<S: PartsWrite + ?Sized>(
339	0	&self,
340	0	sink: &mut S,
341	0	) -> Result<Result<(), Infallible>, fmt::Error> {
342	0	self.0.write_to_parts(sink).map(Ok)
343	0	}
344
345		#[inline]
346	0	fn writeable_length_hint(&self) -> LengthHint {
347	0	self.0.writeable_length_hint()
348	0	}
349
350		#[inline]
351		#[cfg(feature = "alloc")]
352		fn try_write_to_string(&self) -> Result<Cow<'_, str>, (Infallible, Cow<'_, str>)> {
353		Ok(self.0.write_to_string())
354		}
355		}
356
357		/// Testing macros for types implementing [`TryWriteable`].
358		///
359		/// Arguments, in order:
360		///
361		/// 1. The [`TryWriteable`] under test
362		/// 2. The expected string value
363		/// 3. The expected result value, or `Ok(())` if omitted
364		/// 3. [`*_parts_eq`] only: a list of parts (`[(start, end, Part)]`)
365		///
366		/// Any remaining arguments get passed to `format!`
367		///
368		/// The macros tests the following:
369		///
370		/// - Equality of string content
371		/// - Equality of parts ([`*_parts_eq`] only)
372		/// - Validity of size hint
373		///
374		/// For a usage example, see [`TryWriteable`].
375		///
376		/// [`*_parts_eq`]: assert_try_writeable_parts_eq
377		#[macro_export]
378		macro_rules! assert_try_writeable_eq {
379		($actual_writeable:expr, $expected_str:expr $(,)?) => {
380		$crate::assert_try_writeable_eq!($actual_writeable, $expected_str, Ok(()))
381		};
382		($actual_writeable:expr, $expected_str:expr, $expected_result:expr $(,)?) => {
383		$crate::assert_try_writeable_eq!($actual_writeable, $expected_str, $expected_result, "")
384		};
385		($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
386		$crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
387		}};
388		(@internal, $actual_writeable:expr, $expected_str:expr, $expected_result:expr, $($arg:tt)+) => {{
389		use $crate::TryWriteable;
390		let actual_writeable = &$actual_writeable;
391		let (actual_str, actual_parts, actual_error) = $crate::_internal::try_writeable_to_parts_for_test(actual_writeable);
392		assert_eq!(actual_str, $expected_str, $($arg)*);
393		assert_eq!(actual_error, Result::<(), _>::from($expected_result).err(), $($arg)*);
394		let actual_result = match actual_writeable.try_write_to_string() {
395		Ok(actual_cow_str) => {
396		assert_eq!(actual_cow_str, $expected_str, $($arg)+);
397		Ok(())
398		}
399		Err((e, actual_cow_str)) => {
400		assert_eq!(actual_cow_str, $expected_str, $($arg)+);
401		Err(e)
402		}
403		};
404		assert_eq!(actual_result, Result::<(), _>::from($expected_result), $($arg)*);
405		let length_hint = actual_writeable.writeable_length_hint();
406		assert!(
407		length_hint.0 <= actual_str.len(),
408		"hint lower bound {} larger than actual length {}: {}",
409		length_hint.0, actual_str.len(), format!($($arg)*),
410		);
411		if let Some(upper) = length_hint.1 {
412		assert!(
413		actual_str.len() <= upper,
414		"hint upper bound {} smaller than actual length {}: {}",
415		length_hint.0, actual_str.len(), format!($($arg)*),
416		);
417		}
418		actual_parts // return for assert_try_writeable_parts_eq
419		}};
420		}
421
422		/// See [`assert_try_writeable_eq`].
423		#[macro_export]
424		macro_rules! assert_try_writeable_parts_eq {
425		($actual_writeable:expr, $expected_str:expr, $expected_parts:expr $(,)?) => {
426		$crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, Ok(()), $expected_parts)
427		};
428		($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr $(,)?) => {
429		$crate::assert_try_writeable_parts_eq!($actual_writeable, $expected_str, $expected_result, $expected_parts, "")
430		};
431		($actual_writeable:expr, $expected_str:expr, $expected_result:expr, $expected_parts:expr, $($arg:tt)+) => {{
432		let actual_parts = $crate::assert_try_writeable_eq!(@internal, $actual_writeable, $expected_str, $expected_result, $($arg)*);
433		assert_eq!(actual_parts, $expected_parts, $($arg)+);
434		}};
435		}
436
437		#[test]
438		fn test_result_try_writeable() {
439		let mut result: Result<&str, usize> = Ok("success");
440		assert_try_writeable_eq!(result, "success");
441		result = Err(44);
442		assert_try_writeable_eq!(result, "44", Err(44));
443		assert_try_writeable_parts_eq!(result, "44", Err(44), [(0, 2, Part::ERROR)])
444		}