Trait TryWriteable

trait TryWriteable

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)]
);

Associated Types

type Error

Required Methods

fn try_write_to_parts<S: PartsWrite + ?Sized>(self: &Self, sink: &mut S) -> Result<Result<(), <Self as >::Error>, Error>

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.

Provided Methods

fn try_write_to<W: fmt::Write + ?Sized>(self: &Self, sink: &mut W) -> Result<Result<(), <Self as >::Error>, 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 writeable_length_hint(self: &Self) -> LengthHint

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 try_write_to_string(self: &Self) -> Result<Cow<'_, str>, (<Self as >::Error, Cow<'_, str>)>

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);

Implementors