rodrimati1992/const_format_crates rodrimati1992/const_format_crates

  • Stars
    star
    207
  • Rank 189,769 (Top 4 %)
  • Language
    Rust
  • License
    zlib License
  • Created over 4 years ago
  • Updated about 1 year ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
rodrimati1992/const_format_crates
github

rodrimati1992

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Compile-time string formatting

Rust crates-io api-docs

Compile-time string formatting.

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

Rust versions

There are some features that require a variety of stable Rust versions and others that 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: Concatenates integers, bool, char, and &str constants into a &'static str constant.

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

  • str_get: Indexes a &'static str constant, returning None 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 constant times 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 a Case argument.

  • str_replace: Replaces all the instances of a pattern in a &'static str constant with another &'static str constant.

Rust 1.57.0

The "assertcp" feature enables the assertcp, assertcp_eq, and assertcp_ne macros. These macros are like the standard library assert macros, but evaluated at compile-time, with the limitation that they can only have primitive types as arguments (just like concatcp and formatcp).

Rust 1.64.0

The "rust_1_64" feature enables these macros:

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

The "assertc" 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!");

const fn compute_age(s: &str) -> usize { s.len() * 6 }

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);

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

Formatted const assertions

This example demonstrates how you can use the assertcp_ne macro to do compile-time inequality assertions with formatted error messages.

This requires the "assertcp" feature, because using the panic macro at compile-time requires Rust 1.57.0.

use const_format::assertcp_ne;

macro_rules! check_valid_pizza{
    ($user:expr, $topping:expr) => {
        assertcp_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:

error[E0080]: evaluation of constant value failed
  --> src/lib.rs:178:27
   |
20 | check_valid_pizza!("Bob", "pineapple");
   |                           ^^^^^^^^^^^ the evaluated program panicked at '
assertion failed: `(left != right)`
 left: `"pineapple"`
right: `"pineapple"`
You can't put pineapple on pizza, Bob
', src/lib.rs:20:27

Limitations

All of the macros from const_format have these limitations:

  • The formatting macros that expand to &'static strs can only use constants from concrete types, so while a Type::<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");

Plans

None right now.

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

  • "assertc": implies the "fmt" feature, enables the assertc, assertc_eq, and assertc_ne assertion macros.
    This feature was previously named "assert", but it was renamed to avoid confusion with the "assertcp" feature.

  • "assertcp": Requires Rust 1.57.0, implies the "const_generics" feature. Enables the assertcp, assertcp_eq, and assertcp_ne assertion macros.

  • "rust_1_51": Enables the macros listed in the Rust 1.51.0 section. Also changes the the implementation of the concatcp and formatcp macros to use const generics.

  • "rust_1_64": Enables the str_split macro. Allows 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 #![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.

More Repositories

1

abi_stable_crates

Rust-to-Rust ffi,ffi-safe equivalents of std types,and creating libraries loaded at startup.
Rust
525
star
2

konst

Const equivalents of std functions, compile-time comparison, and parsing.
Rust
83
star
3

core_extensions

extensions to core/std library types.
Rust
13
star
4

type_level

Libraries for declaring and using type-level values.
Rust
11
star
5

structural_crates

field accessor traits,and emulation of structural types
Rust
11
star
6

constmuck

Const equivalents of many bytemuck functions
Rust
11
star
7

typewit

type-witness-based abstractions, used for emulating polymorphism in const fns
Rust
9
star
8

tstr_crates

Type-level strings
Rust
9
star
9

const_panic

const panic with formatting
Rust
7
star
10

break_array

For breaking array indexing(works on Rust 1.41.0).
Rust
5
star
11

multindex

Index slices with multiple const indices/ranges
Rust
4
star
12

zeroable_crates

Provides a derive for `bytemuck::Zeroable`
Rust
4
star
13

const_base

For decoding/encoding base 64/32/16 strings at compile-time.
Rust
3
star
14

multiconst

Destructure an expression into multiple constants
Rust
2
star
15

notzero

macro for constructing `std::num::NonZero*` from constants
Rust
1
star
16

repr_offset_crates

Offsets of fields for types with a stable layout
Rust
1
star
17

arrcat

Array concatenation
Rust
1
star