custom-format
This crate extends the standard formatting syntax with custom format specifiers, by providing custom formatting macros.
It uses :
(a space and a colon) as a separator before the format specifier, which is not a syntax currently accepted and allows supporting standard specifiers in addition to custom specifiers.
This library comes in two flavors:
-
With the
compile-time
feature, the set of possible custom format specifiers is defined at compilation, so invalid specifiers can be checked at compile-time. This allows the library to have the same performance as when using the standard library formatting traits. -
With the
runtime
feature, the formatting method dynamically checks the format specifier at runtime for each invocation. This is a slower version, but has a lower MSRV for greater compatibility.
Documentation
Documentation is hosted on docs.rs.
Example with the compile-time
feature
use compile_time as cfmt;
use custom_formatter;
use fmt;
) => ;
}
impl_custom_format_for_datetime!;
let date_time = DateTime ;
// Expands to:
//
// match (&(date_time), &("The date time is")) {
// (arg0, arg1) => {
// ::std::println!(
// "{0}: {1}-{2}-{3} {4}:{5}:{6}.{7}",
// arg1,
// ::custom_format::custom_formatter!("%Y", arg0),
// ::custom_format::custom_formatter!("%m", arg0),
// ::custom_format::custom_formatter!("%d", arg0),
// ::custom_format::custom_formatter!("%H", arg0),
// ::custom_format::custom_formatter!("%M", arg0),
// ::custom_format::custom_formatter!("%S", arg0),
// ::custom_format::custom_formatter!("%9N", arg0)
// )
// }
// }
//
// Output: "The date time is: 1836-05-18 23:45:54.123456789"
//
println!;
// Compile-time error since "%h" is not a valid format specifier
// cfmt::println!("{0 :%h}", date_time);
Example with the runtime
feature
use ;
use fmt;
let date_time = DateTime ;
// Expands to:
//
// match (&(date_time), &("The date time is")) {
// (arg0, arg1) => {
// ::std::println!(
// "{0}: {1}-{2}-{3} {4}:{5}:{6}.{7}",
// arg1,
// ::custom_format::runtime::CustomFormatter::new("%Y", arg0),
// ::custom_format::runtime::CustomFormatter::new("%m", arg0),
// ::custom_format::runtime::CustomFormatter::new("%d", arg0),
// ::custom_format::runtime::CustomFormatter::new("%H", arg0),
// ::custom_format::runtime::CustomFormatter::new("%M", arg0),
// ::custom_format::runtime::CustomFormatter::new("%S", arg0),
// ::custom_format::runtime::CustomFormatter::new("%9N", arg0)
// )
// }
// }
//
// Output: "The date time is: 1836-05-18 23:45:54.123456789"
//
println!;
// Panic at runtime since "%h" is not a valid format specifier
// cfmt::println!("{0 :%h}", date_time);
Limitations
To improve compilation time, this crate doesn't use the syn
crate for parsing tokens, and instead use a simple method to separate arguments of procedural macros: the arguments are separated by the ,
token when not in a delimited group.
As a result, it cannot parse correctly complex expressions such as the following statement:
// Compilation error due to incorrect parsing
println!;
The workaround is simply to add an additional delimited group, or to define a new variable:
// No compilation error
println!;
println!;
let map = new;
println!;
println!;
Compiler support
Requires rustc 1.45+
for the runtime
feature and rustc 1.51+
for the compile-time
feature.
License
This project is licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.