Crate writeable

writeable is a utility crate of the ICU4X project.

It includes Writeable, a core trait representing an object that can be written to a sink implementing std::fmt::Write. It is an alternative to std::fmt::Display with the addition of a function indicating the number of bytes to be written.

Writeable improves upon std::fmt::Display in two ways:

1. More efficient, since the sink can pre-allocate bytes.
2. Smaller code, since the format machinery can be short-circuited.

Examples

use std::fmt;
use writeable::assert_writeable_eq;
use writeable::LengthHint;
use writeable::Writeable;

struct WelcomeMessage<'s> {
    pub name: &'s str,
}

impl<'s> Writeable for WelcomeMessage<'s> {
    fn write_to<W: fmt::Write + ?Sized>(&self, sink: &mut W) -> fmt::Result {
        sink.write_str("Hello, ")?;
        sink.write_str(self.name)?;
        sink.write_char('!')?;
        Ok(())
    }

    fn writeable_length_hint(&self) -> LengthHint {
        // "Hello, " + '!' + length of name
        LengthHint::exact(8 + self.name.len())
    }
}

let message = WelcomeMessage { name: "Alice" };
assert_writeable_eq!(&message, "Hello, Alice!");

// Types implementing `Writeable` are recommended to also implement `fmt::Display`.
// This can be simply done by redirecting to the `Writeable` implementation:
writeable::impl_display_with_writeable!(WelcomeMessage<'_>);
assert_eq!(message.to_string(), "Hello, Alice!");

Modules

• adapters
  Helper types for trait impls.

Macros

• assert_try_writeable_eq
  Testing macros for types implementing TryWriteable.
• assert_try_writeable_parts_eq
  See assert_try_writeable_eq.
• assert_writeable_eq
  Testing macros for types implementing Writeable.
• assert_writeable_parts_eq
  See assert_writeable_eq.
• impl_display_with_writeable
  Implements Display for types that implement Writeable.

Structs

• LengthHint
  A hint to help consumers of Writeable pre-allocate bytes before they call write_to.
• Part
  Parts are used as annotations for formatted strings.

Traits

• PartsWrite
  A sink that supports annotating parts of the string with Parts.
• TryWriteable
  A writeable object that can fail while writing.
• Writeable
  Writeable is an alternative to std::fmt::Display with the addition of a length function.

Functions

• cmp_str
  Compares the contents of a Writeable to the given bytes without allocating a String to hold the Writeable contents.
• cmp_utf8
  Compares the contents of a Writeable to the given UTF-8 bytes without allocating memory.
• to_string_or_borrow
  Writes the contents of a Writeable to a string, returning a reference to a slice if it matches the provided reference bytes, and allocating a String otherwise.