Crate aya_ufmt 

μfmt, a (6-40x) smaller, (2-9x) faster and panic-free alternative to core::fmt

Design goals

From highest priority to lowest priority

• Optimized for binary size and speed (rather than for compilation time)
• No dynamic dispatch in generated code
• No panicking branches in generated code, when optimized
• No recursion where possible

Features

• Debug and Display-like traits
• core::write!-like macro
• A generic Formatter<'_, impl uWrite> instead of a single core::Formatter; the uWrite trait has an associated error type so each writer can choose its error type. For example, the implementation for std::String uses Infallible as its error type.
• core::fmt::Formatter::debug_struct-like API
• #[derive(uDebug)]
• Pretty formatting ({:#?}) for uDebug

Non-features

These are out of scope

• Padding, alignment and other formatting options
• Formatting floating point numbers

Examples

• uwrite! / uwriteln!

use ufmt::{derive::uDebug, uwrite};

#[derive(uDebug)]
struct Pair { x: u32, y: u32 }

let mut s = String::new();
let pair = Pair { x: 1, y: 2 };
uwrite!(s, "{:?}", pair).unwrap();
assert_eq!(s, "Pair { x: 1, y: 2 }");

• implementing uWrite

When implementing the uWrite trait you should prefer the ufmt_write::uWrite crate over the ufmt::uWrite crate for better forward compatibility.

use core::convert::Infallible;

use ufmt_write::uWrite;

struct MyWriter;

impl uWrite for MyWriter {
    type Error = Infallible;

    fn write_str(&mut self, s: &str) -> Result<(), Self::Error> {
        // ..
        Ok(())
    }
}

• writing a macro_rules! macro that uses uwrite! (or uwriteln!).

Both ufmt macros are implemented using proc-macro-hack; care is needed to avoid running into the compiler bug #43081. See also dtolnay/proc-macro-hack#46.

// like `std::format!` it returns a `std::String` but uses `uwrite!` instead of `write!`
macro_rules! uformat {
    // IMPORTANT use `tt` fragments instead of `expr` fragments (i.e. `$($exprs:expr),*`)
    ($($tt:tt)*) => {{
        let mut s = String::new();
        match ufmt::uwrite!(&mut s, $($tt)*) {
            Ok(_) => Ok(s),
            Err(e) => Err(e),
        }
    }}
}

Benchmarks

The benchmarks ran on a ARM Cortex-M3 chip (thumbv7m-none-eabi).

The benchmarks were compiled with nightly-2019-05-01, -C opt-level=3, lto = true, codegen-units = 1.

In all benchmarks x = i32::MIN and y = i32::MIN plus some obfuscation was applied to prevent const-propagation of the *write! arguments.

The unit of time is one core clock cycle: 125 ns (8 MHz)

The .text and .rodata columns indicate the delta (in bytes) when commenting out the *write! statement.

Code	Time	%	.text	%	.rodata	%
write!("Hello, world!")	154	~	1906	~	248	~
uwrite!("Hello, world!")	20	13.0%	34	1.8%	16	6.5%
write!(w, "{}", 0i32)	256	~	1958	~	232	~
uwrite!(w, "{}", 0i32)	37	14.5%	288	14.7%	0	0%
write!(w, "{}", x)	381	~
uwrite!(w, "{}", x)	295	77.4%
write!(w, "{:?}", Pair { x: 0, y: 0 })	996	~	4704	~	312	~
uwrite!(w, "{:?}", Pair { x: 0, y: 0 })	254	25.5%	752	16.0%	24	7.7%
write!(w, "{:?}", Pair { x, y })	1264	~
uwrite!(w, "{:?}", Pair { x, y })	776	61.4%
write!(w, "{:#?}", Pair { x: 0, y: 0 })	2853	~	4710	~	348	~
uwrite!(w, "{:#?}", Pair { x: 0, y: 0 })	301	10.6%	754	16.0%	24	6.9%
write!(w, "{:#?}", Pair { x, y })	3693	~
uwrite!(w, "{:#?}", Pair { x, y })	823	22.3%

Benchmark program:

static X: AtomicI32 = AtomicI32::new(i32::MIN); // or `0`
static Y: AtomicI32 = AtomicI32::new(i32::MIN); // or `0`

#[exception]
fn PendSV() {
   // read DWT.CYCCNT here

   let x = X.load(Ordering::Relaxed);
   let y = Y.load(Ordering::Relaxed);

   let p = Pair { x, y };

   uwrite!(&mut W, "{:#?}", p).ok();

   // write!(&mut W, "{:#?}", p).ok();

   asm::bkpt(); // read DWT.CYCCNT here
}

Writer used in the benchmarks:

use core::{convert::Infallible, fmt, ptr};

use ufmt::uWrite;

struct W;

impl uWrite for W {
    type Error = Infallible;

    fn write_str(&mut self, s: &str) -> Result<(), Infallible> {
        s.as_bytes()
            .iter()
            .for_each(|b| unsafe { drop(ptr::read_volatile(b)) });

        Ok(())
    }
}

impl fmt::Write for W {
    fn write_str(&mut self, s: &str) -> fmt::Result {
        s.as_bytes()
            .iter()
            .for_each(|b| unsafe { drop(ptr::read_volatile(b)) });

        Ok(())
    }
}

Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on stable Rust 1.34 and up. It might compile on older versions but that may change in any new patch release.

Modules

derive

Derive macros

Macros

uwrite

Write formatted data into a buffer

uwriteln

Write formatted data into a buffer, with a newline appended

Structs

DebugList

A struct to help with uDebug implementations.

DebugMap

A struct to help with uDebug implementations.

DebugStruct

A struct to help with uDebug implementations.

DebugTuple

A struct to help with uDebug implementations.

Formatter

Configuration for formatting

Traits

uDebug

Just like core::fmt::Debug

uDisplay

Just like core::fmt::Display

uWrite

A collection of methods that are required / used to format a message into a stream.