Crate interpolator

Runtime implementation of format!.

std::fmt compatible formatting

All options but the fill character for alignment is supported (due to rust-lang/rfcs#3394).

Though the non Display traits need to be enabled through features.

use interpolator::{format, Formattable};

let formatted = format(
    "{value:+05}", // could be dynamic
    &[("value", Formattable::display(&12))]
        .into_iter()
        .collect::<HashMap<_, _>>(),
)?;

assert_eq!(formatted, format!("{:+05}", 12));

i iter format

The feature iter enables an additional format trait i, it allows to format a list of values with a format string and an optional join expression.

The syntax is {list:i(the format string, '{}' is the array element)(the join)}, an empty join can also be omitted {list:i({})}. If join is omitted the format string {} can be omitted as well {list:i}.

Should you need to use ) inside your format string or join, you can add # similar to rust’s raw string (i.e. #(({}))#).

It is also possible to only iterate a sub-slice specified through a range before the format string, i.e. {list:i1..4}. For open ranges range bounds can also be omitted. To index from the end, you can use negative range bounds.

It is also possible to index a single value by only specifying an isize {list:i1}.

A Formattable implementing iter is created using Formattable::iter:

// HashMap macro
use collection_literals::hash;
use interpolator::{format, Formattable};
// Needs to be a slice of references because `Formattable::display` expects a
// reference
let items = [&"hello", &"hi", &"hey"].map(Formattable::display);
let items = Formattable::iter(&items);
let format_str = "Greetings: {items:i..-1(`{}{outside}`)(, )} and `{items:i-1}{outside}`";
assert_eq!(
    format(format_str, &hash!("items" => items, "outside" => Formattable::display(&'!')))?,
    "Greetings: `hello!`, `hi!` and `hey!`"
);

See format() and write() for details.

Macros

To simplify creating contexts, some macros are provided.

• context! creates a HashMap<&str, Formattable> to be used with format().
• list! creates a Formattable implementing supporting iter.
• iformat! and iwrite! macros matching the behaviour of format() and write() but allowing to specify context directly.
• Most of std’s formatting macros are supported with an i prefix:
  • iwriteln!
  • iprint!
  • iprintln!
  • ieprint!
  • ieprintln!

Features

By default only Display is supported, the rest of the formatting traits can be enabled through the following features.

• debug enables ?, x? and X? trait specifiers
• number enables x, X, b, o, e and E trait specifiers
• pointer enables p trait specifiers
• iter enables i trait specifier

Macros

context

Creates a context for use with this crate’s format() and write() functions.

ieprint

eprint! but using iformat!.

ieprintln

eprintln! but using iformat!.

iformat

format() as a macro to allow specifying the context directly.

iprint

print! but using iformat!.

iprintln

println! but using iformat!.

iwrite

write() as a macro to allow specifying the context directly.

iwriteln

Like writeln! but using write().

list

Creates a list of formattable values, applying th specified traits, or display if without a trait specifier.

Structs

Formattable

Utility struct holding references to the trait implementation of a value to enable runtime verification and execution of them

Enums

Error

Error returned by format().

ParseError

Error caused by invalid format string

Trait

The trait used to format.

Traits

Context

Context for format and write

Functions

format

Runtime version of format!.

write

Runtime version of write!.