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