Crate rtformat 

Runtime string formatting with std::fmt-compatible placeholder syntax.

• {} implicit positional arguments; {0} / {1} explicit indices (reusable)
• Types: {:?} {:#?} {:x} {:X} {:o} {:b} {:e} {:E}
• Alignment and fill: {:<10} {:>10} {:^10} {:_>10}
• Sign / radix prefix / zero padding: {:+} {:#x} {:010}
• Width and precision: {:.3} {:1$} {:.1$} (n$ takes the width/precision from argument n)
• {{ / }} escapes
• Format into any core::fmt::Write sink; precompiled templates via Template

Not supported: named arguments {name}, pointers {:p}, hexadecimal debug {x?} / {X?}.

This crate is #![no_std]-compatible and requires alloc.

Custom argument types

Types implementing Display and/or Debug can derive FormatArg. The derive adapts: {} prefers Display and falls back to Debug, while {:?} / {:#?} require Debug:

use core::fmt;
use rtformat::{rformat, Format, FormatArg};

#[derive(Debug, FormatArg)]
struct Color(u8, u8, u8);

impl fmt::Display for Color {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "#{:02x}{:02x}{:02x}", self.0, self.1, self.2)
    }
}

assert_eq!(rformat!("{}", Color(255, 128, 0)), "#ff8000");

For full control over each format type, implement FormatArg manually instead.

Examples

use rtformat::{rformat, Format};

assert_eq!(rformat!("Hello {}!", "world"), "Hello world!");
assert_eq!("{} + {} = {2}".format(&(1, 2, 3)), "1 + 2 = 3");
assert_eq!(rformat!("{:#010x}", 255), "0x000000ff");

Builder API

Templates can also be formatted incrementally with FormatBuilder, adding one argument per call:

use rtformat::Format;

let s = "{} + {} = {2}".builder().arg(&1).arg(&2).arg(&3).build();
assert_eq!(s, "1 + 2 = 3");

Precompiled templates

The one-shot APIs parse the template on every call. Template parses once, formats many times, and can also write into any core::fmt::Write sink (appending, not overwriting):

use rtformat::Template;

let tpl = Template::parse("{} + {} = {2}")?;
assert_eq!(tpl.format(&(1, 2, 3)), "1 + 2 = 3");

let mut log = String::from("log: ");
tpl.try_write_to(&mut log, &(1, 2, 3))?;
assert_eq!(log, "log: 1 + 2 = 3");

All commonly used items are also available through prelude:

use rtformat::prelude::*;

assert_eq!(rformat!("Hello {}!", "world"), "Hello world!");

Modules

prelude

Convenience re-exports of the most commonly used items.

Macros

rformat

Formats arguments into a template string at runtime.

Structs

FormatBuilder

Incrementally formats a template string by adding one argument at a time.

Template

A template string parsed once and formattable many times.

Enums

FormatError

Error returned by Format::try_format.

FormatType

The trailing type character of a {...} placeholder spec.

Traits

Format

A template string that can be formatted with runtime arguments.

FormatArg

A value that can be substituted into a {} placeholder.

FormatArgRef

A type that can be passed to FormatBuilder::arg.

FormatParam

All arguments of one format call, handed to the visitor one by one in declaration order.

Derive Macros

FormatArg

Derives rtformat::FormatArg, adapting to whichever of Display and Debug the type implements — implementing either one is enough.