Crate const_format[−][src]
Expand description
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, some that require Rust 1.51.0, and others that require Rust nightly, the sections below describe the features that are available for each version.
Rust 1.46.0
These macros are the only things available in Rust 1.46.0:
-
concatcp
: Concatenatesintegers
,bool
,char
, and&str
constants into a&'static str
constant. -
formatcp
:format
-like formatting which takesintegers
,bool
,char
, and&str
constants, and emits a&'static str
constant. -
str_get
: Indexes a&'static str
constant, returningNone
when the index is out of bounds. -
str_index
: Indexes a&'static str
constant. -
str_repeat
: Creates a&'static str
by repeating a&'static str
constanttimes
times. -
str_splice
: Replaces a substring in a&'static str
constant.
Rust 1.51.0
By enabling the “const_generics” feature, you can use these macros:
-
map_ascii_case
: Converts a&'static str
constant to a different casing style, determined by aCase
argument. -
str_replace
: Replaces all the instances of a pattern in a&'static str
constant with another&'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:
-
concatc
: Concatenates many standard library and user defined types into a&'static str
constant. -
formatc
:format
-like macro that can format many standard library and user defined types into a&'static str
constant. -
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.
The “assert” feature enables the assertc
, assertc_eq
, assertc_ne
macros,
and the “fmt” feature.
These macros are like the standard library assert macros, but evaluated at compile-time.
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 the assertc_ne
macro to
do compile-time inequality assertions with formatted error messages.
This requires the “assert” feature,because as of writing these docs (2020-09-XX), panicking at compile-time requires a nightly feature.
#![feature(const_mut_refs)]
use const_format::{StrWriter, assertc_ne, writec};
use const_format::utils::str_eq;
macro_rules! check_valid_pizza{
($user:expr, $topping:expr) => {
assertc_ne!(
$topping,
"pineapple",
"You can't put pineapple on pizza, {}",
$user,
);
}
}
check_valid_pizza!("John", "salami");
check_valid_pizza!("Dave", "sausage");
check_valid_pizza!("Bob", "pineapple");
This is the compiler output, the first compilation error is there to have an indicator of what assertion failed, and the second is the assertion failure:
error: any use of this value will cause an error
--> src/lib.rs:140:1
|
22 | check_valid_pizza!("Bob", "pineapple");
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ exceeded interpreter step limit (see `#[const_eval_limit]`)
|
= 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)
error[E0080]: could not evaluate constant
--> /const_format/src/panicking.rs:32:5
|
32 | .
| ^ the evaluated program panicked at '
--------------------------------------------------------------------------------
module_path: rust_out
line: 22
assertion failed: LEFT != RIGHT
left: "pineapple"
right: "pineapple"
You can't put pineapple on pizza, Bob
--------------------------------------------------------------------------------
', /const_format/src/panicking.rs:31:1
|
= note: this error originates in a macro (in Nightly builds, run with -Z macro-backtrace for more info)
error: aborting due to 2 previous errors
Limitations
All of the macros from const_format
have these limitations:
-
The formatting macros that expand to
&'static str
s can only use constants from concrete types, so while aType::<u8>::FOO
argument would be fine,Type::<T>::FOO
would not be (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");
Renaming crate
All function-like macros from const_format
can be used when the crate is renamed.
The ConstDebug
derive macro has the #[cdeb(crate = "foo::bar")]
attribute to
tell it where to find the const_format
crate.
Example of renaming the const_format
crate in the Cargo.toml file:
cfmt = {version = "0.*", package = "const_format"}
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. -
“assert”: implies the “fmt” feature, enables the assertion macros.
-
“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. -
“const_generics”: Requires Rust 1.51.0. Enables the macros listed in the Rust 1.51.0 section. Also changes the the implementation of the
concatcp
andformatcp
macros to use const generics.
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::Result;
pub use crate::fmt::StrWriter;
pub use crate::fmt::StrWriterMut;
Modules
fmt
std::fmt
-like
api that can be used at compile-time.
fmt
Types for the documentation examples.
Marker traits for types that can be formatted and/or be written to.
fmt
Miscelaneous functions.
Some wrapper types.
Macros
fmt
Constructs an AsciiStr
constant from an ascii string,
assert
Compile-time assertions with formatting.
assert
Compile-time equality assertion with formatting.
assert
Compile-time inequality assertion with formatting.
For debug formatting of some specific generic std types, and other types.
Coerces a reference to a type that has a const_*_fmt
method.
fmt
Concatenates constants of standard library and/or user-defined types into a &'static str
.
Concatenates constants of primitive types into a &'static str
.
fmt
Formats constants of standard library and/or user-defined types into a &'static str
.
Formats constants of primitive types into a &'static str
fmt
For implementing debug or display formatting “manually”.
const_generics
Converts the casing style of a &'static str
constant,
ignoring non-ascii unicode characters.
Indexes a &'static str
constant,
returning None
when the index is not on a character boundary.
Indexes a &'static str
constant.
Creates a &'static str
by repeating a &'static str
constant times
times
const_generics
Replaces all the instances of $pattern
in $input
(a &'static str
constant) with $replace_with
(a &'static str
constant).
Replaces a substring in a &'static str
constant.
Returns both the new resulting &'static str
, and the replaced substring.
Converts a &'static StrWriter
to a &'static str
, in a const
/static
initializer.
fmt
For returning early on an error, otherwise evaluating to ()
.
fmt
Equivalent to Result::unwrap
, for use with const_format::Error
errors.
Equivalent to Result::unwrap_or_else
but allows returning from the enclosing function.
fmt
Writes some formatted standard library and/or user-defined types into a buffer.
Structs
fmt
An ascii string slice.
fmt
Wrapper for many std types,
which implements the const_debug_fmt
and/or const_display_fmt
methods for them.
fmt
Wrapper for writing a range of a string slice.
The return value of str_splice
Enums
The casing style of a string.
Derive Macros
derive
Derives const debug formatting for a type.