Crate const_format

Compile-time string formatting.

This crate provides types and macros for formatting strings at compile-time.

Rust versions

There are some features that require Rust 1.46.0, and others that require Rust nightly, the sections below describe the features that are available.

Rust 1.46.0

These macros are the only things available in Rust 1.46.0:

• concatcp: Concatenates integers, bool, and &str constants into a &'static str constant.

• formatcp: format-like formatting which takes integers, bool, and &str constants, and emits a &'static str constant.

Rust nightly

By enabling the "fmt" feature, you can use a std::fmt-like API.

This requires the nightly compiler because it uses mutable references in const fn, which have not been stabilized as of writing these docs.

All the other features of this crate are implemented on top of the const_format::fmt API:

• formatc: format-like macro that can format many standard library and user defined types.

• writec: write-like macro that can format many standard library and user defined types into a type that implements WriteMarker.

The "derive" feature enables the ConstDebug macro, and the "fmt" feature.
ConstDebug derives the FormatMarker trait, and implements an inherent const_debug_fmt method for compile-time debug formatting.

Examples

Concatenation of primitive types

This example works in Rust 1.46.0.

use const_format::concatcp;

const NAME: &str = "Bob";
const FOO: &str = concatcp!(NAME, ", age ", 21u8,"!");

assert_eq!(FOO, "Bob, age 21!");

Formatting primitive types

This example works in Rust 1.46.0.

use const_format::formatcp;

const NAME: &str = "John";

const FOO: &str = formatcp!("{NAME}, age {}!", compute_age(NAME));

assert_eq!(FOO, "John, age 24!");

Formatting custom types

This example demonstrates how you can use the ConstDebug derive macro, and then format the type into a &'static str constant.

This example requires Rust nightly, and the "derive" feature.

#![feature(const_mut_refs)]

use const_format::{ConstDebug, formatc};

#[derive(ConstDebug)]
struct Message{
    ip: [Octet; 4],
    value: &'static str,
}

#[derive(ConstDebug)]
struct Octet(u8);

const MSG: Message = Message{
    ip: [Octet(127), Octet(0), Octet(0), Octet(1)],
    value: "Hello, World!",
};

const FOO: &str = formatc!("{:?}", MSG);

assert_eq!(
    FOO,
    "Message { ip: [Octet(127), Octet(0), Octet(0), Octet(1)], value: \"Hello, World!\" }"
);

Formatted const panics

This example demonstrates how you can use a StrWriter to format a compile-time panic message.

As of writing these docs (2020-08-29), panicking at compile-time requires a nightly feature, and only supports passing a &'static str argument, so this only works in the initialization block of const items.

#![feature(const_mut_refs)]
#![feature(const_panic)]

use const_format::{StrWriter, strwriter_as_str, writec};
use const_format::utils::str_eq;

struct PizzaError;

const fn write_message(
    buffer: &mut StrWriter,
    bought_by: &str,
    topping: &str,
) -> Result<(), PizzaError> {
    buffer.clear();
    let mut writer = buffer.as_mut();
    if str_eq(topping, "pineapple") {
        let _ = writec!(
            writer,
            "\n{SEP}\n\nYou can't put pineapple on pizza, {}.\n\n{SEP}\n",
            bought_by,
            SEP = "----------------------------------------------------------------"
        );
        return Err(PizzaError);
    }
    Ok(())
}

const CAP: usize = 256;
// Defined a `const fn` as a workaround for mutable references not
// being allowed in `const`ants.
const fn message_and_result(
    bought_by: &str,
    topping: &str,
) -> (StrWriter<[u8; CAP]>, Result<(), PizzaError>) {
    let mut buffer = StrWriter::new([0; CAP]);
    let res = write_message(&mut buffer, bought_by, topping);
    (buffer, res)
}

const _: () = {
    if let (buffer, Err(_)) = message_and_result("Bob", "pineapple") {
        let promoted: &'static StrWriter = &{buffer};
        let message = strwriter_as_str!(promoted);
        panic!(message);
    }
};

This is what it prints in rust nightly :

error: any use of this value will cause an error
  --> src/lib.rs:166:9
   |
43 | / const _: () = {
44 | |     if let (buffer, Err(_)) = message_and_result("Bob", "pineapple") {
45 | |         let promoted: &'static StrWriter = &{buffer};
46 | |         let message = strwriter_as_str!(promoted);
47 | |         panic!(message);
   | |         ^^^^^^^^^^^^^^^^ the evaluated program panicked at '
----------------------------------------------------------------

You can't put pineapple on pizza, Bob.

----------------------------------------------------------------
', src/lib.rs:47:9
48 | |     }
49 | | };
   | |__-
   |
   = note: `#[deny(const_err)]` on by default
   = note: this error originates in a macro (in Nightly builds, run with -Z macro-backtrace for more info)

Limitations

All of the macros from const_format have these limitations:

• The formatting macros that expand to &'static strs can only use constants of concrete types, so while Type::<u8>::FOO is fine,Type::<T>::FOO is not (T being a type parameter).

• Integer arguments must have a type inferrable from context, more details in the Integer arguments section.

• They cannot be used places that take string literals. So #[doc = "foobar"] cannot be replaced with #[doc = concatcp!("foo", "bar") ].

Integer arguments

Integer arguments must have a type inferrable from context. so if you only pass an integer literal it must have a suffix.

Example of what does compile:

const N: u32 = 1;
assert_eq!(const_format::concatcp!(N + 1, 2 + N), "23");

assert_eq!(const_format::concatcp!(2u32, 2 + 1u8, 3u8 + 1), "234");

Example of what does not compile:

assert_eq!(const_format::concatcp!(1 + 1, 2 + 1), "23");

Cargo features

• "fmt": Enables the std::fmt-like API, requires Rust nightly because it uses mutable references in const fn.
  This feature includes the formatc/writec formatting macros.

• "derive": implies the "fmt" feature, provides the ConstDebug derive macro to format user-defined types at compile-time.
  This implicitly uses the syn crate, so clean compiles take a bit longer than without the feature.

• "constant_time_as_str": implies the "fmt" feature. An optimization that requires a few additional nightly features, allowing the as_bytes_alt methods and slice_up_to_len_alt methods to run in constant time, rather than linear time proportional to the truncated part of the slice.

No-std support

const_format is unconditionally #![no_std], it can be used anywhere Rust can be used.

Minimum Supported Rust Version

const_format requires Rust 1.46.0, because it uses looping an branching in const contexts.

Features that require newer versions of Rust, or the nightly compiler, need to be explicitly enabled with cargo features.

Re-exports

pub use crate::fmt::Error;

pub use crate::fmt::Formatter;

pub use crate::fmt::FormattingFlags;

pub use crate::fmt::StrWriter;

pub use crate::fmt::StrWriterMut;

Modules

fmt	std::fmt-like api that can be used at compile-time.
for_examples	Types for the documentation examples.
marker_traits	Marker traits for types that can be formatted and/or be written to.
utils	Miscelaneous functions.
wrapper_types	Some wrapper types.

Macros

ascii_str	Constructs an AsciiStr constant from an ascii string,
call_debug_fmt	For debug formatting of some specific generic std types, and other types.
coerce_to_fmt	Coerces a reference to a type that has a const_*_fmt method.
concatcp	Concatenates constants of primitive types into a &'static str.
formatc	Formats constants of standard library and/or user-defined types into a &'static str.
formatcp	Formats constants of primitive types into a &'static str
impl_fmt	For implementing debug or display formatting "manually".
strwriter_as_str	Converts a &'static StrWriter to a &'static str, in a const/static initializer.
try_	For returning early on an error, otherwise evaluating to ().
unwrap	Equivalent to Result::unwrap, for use with const_format::Error errors.
unwrap_or_else	Equivalent to Result::unwrap_or_else but allows returning from the enclosing function.
writec	Writes some formatted standard library and/or user-defined types into a buffer.

Structs

AsciiStr	An ascii string slice.
PWrapper	Wrapper for many std types, which implements the const_debug_fmt and/or const_display_fmt methods for them.
Sliced	Wrapper for writing a range of a string slice.

Derive Macros

ConstDebug

Derives const debug formatting for a type.