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
: Concatenatesintegers
,bool
, and&str
constants into a&'static str
constant. -
formatcp
:format
-like formatting which takesintegers
,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 implementsWriteMarker
.
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 concatcp;
const NAME: &str = "Bob";
const FOO: &str = concatcp!;
assert_eq!;
Formatting primitive types
This example works in Rust 1.46.0.
use formatcp;
const NAME: &str = "John";
const FOO: &str = formatcp!;
assert_eq!;
# const
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 str
s can only use constants of concrete types, so whileType::<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!;
assert_eq!;
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 theformatc
/writec
formatting macros. -
"derive": implies the "fmt" feature, provides the
ConstDebug
derive macro to format user-defined types at compile-time. This implicitly uses thesyn
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 andslice_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.