# `aya-ufmt`

This is a fork of https://github.com/japaric/ufmt, tweaked to play nice with the
eBPF kernel verifier.

# `μfmt`

> A (6-40x) smaller, (2-9x) faster and panic-free alternative to `core::fmt`

![Call graph of formatting structs](cg.png)

Call graph of a program that formats some structs (generated using
[`cargo-call-stack`]). Source code can be found at the bottom of this file. The
program was compiled with `-C opt-level=z`.

[`cargo-call-stack`]: https://crates.io/crates/cargo-call-stack

## [API docs](https://docs.rs/ufmt)

## 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`

# 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.

## License

All source code (including code snippets) is licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  [https://www.apache.org/licenses/LICENSE-2.0][L1])

- MIT license ([LICENSE-MIT](LICENSE-MIT) or
  [https://opensource.org/licenses/MIT][L2])

[L1]: https://www.apache.org/licenses/LICENSE-2.0
[L2]: https://opensource.org/licenses/MIT

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
licensed as above, without any additional terms or conditions.

## Appendix

### Formatting structs (snippet)

Full source code in [nopanic/examples/struct.rs](nopanic/examples/struct.rs).

``` rust
// ..

#[derive(Clone, Copy, uDebug)]
struct Pair {
    x: i32,
    y: i32,
}

static X: AtomicI32 = AtomicI32::new(0);
static Y: AtomicI32 = AtomicI32::new(0);

#[exception]
fn PendSV() {
    let x = X.load(Ordering::Relaxed);
    let y = Y.load(Ordering::Relaxed);

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

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

    uwrite!(&mut W, "{:?}", I32(x)).unwrap();
    uwrite!(&mut W, "{:#?}", I32(x)).unwrap();

    uwrite!(&mut W, "{:?}", Tuple(x, y)).unwrap();
    uwrite!(&mut W, "{:#?}", Tuple(x, y)).unwrap();

    let pair = Pair { x, y };
    uwrite!(&mut W, "{:?}", pair).unwrap();
    uwrite!(&mut W, "{:#?}", pair).unwrap();

    let first = pair;
    let second = pair;
    uwrite!(&mut W, "{:?}", Nested { first, second }).unwrap();
    uwrite!(&mut W, "{:#?}", Nested { first, second }).unwrap();
}

// ..
```