Expand description
Compile-time string operations. See the macro list for what you need.
MSRV: Rust 1.77.0
§Troubleshoot
You don’t have to care about this section unless you come across some compile errors about const evaluation.
error[E0435]: attempt to use a non-constant value in a constant
There are mainly two kinds of macros in this crate, which have different requirements for the arguments.
§const-context only
These macros can only be used in const contexts.
The expanded code is equivalent to compute new constant items.
It implies that the arguments of these macros must be constant values,
similar to consteval
in C++ world.
The following examples will not work:
const fn foo(a: &str, b: &str) -> &str {
const_str::concat!(a, b)
}
const C: &str = {
let a = "Hello";
let b = "World";
const_str::concat!(a, b);
};
Instead, this way will work:
const A: &str = "Hello";
const B: &str = "World";
const C: &str = const_str::concat!(A, " ", B);
assert_eq!(C, "Hello World");
§const-fn compatible
These macros can be used in const contexts and const functions.
The expanded code is equivalent to calling const functions.
It implies that the arguments of these macros can be any expressions,
similar to constexpr
in C++ world.
const fn calc(y: &str, m: &str, d: &str) -> u64 {
let y = const_str::parse!(y, u64);
let m = const_str::parse!(m, u64);
let d = const_str::parse!(d, u64);
(y * 10000 + m * 100 + d)
}
const TIME: u64 = calc("2025", "01", "26");
assert_eq!(TIME, 20250126);
You can also use these macros in normal functions, but they may be much slower than the runtime equivalents. It’s recommended to use them only if you need compile-time evaluation.
Macros§
- chain
- Chains multiple macro calls together.
- compare
- Compares two strings lexicographically.
- concat
- Concatenates values into a string slice.
- concat_
bytes - Concatenates values into a byte slice.
- contains
- Returns
true
if the given pattern matches a sub-slice of this string slice. - convert_
ascii_ case - Converts a string slice to a specified case. Non-ascii characters are not affected.
- convert_
case proc
orcase
- Converts a string literal to a specified case.
- cstr
- Converts a string slice to
&CStr
. - encode
- Encode a string slice with a specified encoding.
- encode_
z - Encode a string slice with a specified encoding and append a nul character.
- ends_
with - Returns
true
if the given pattern matches a suffix of this string slice. - eq_
ignore_ ascii_ case - Checks that two (string) slices are an ASCII case-insensitive match.
- equal
- Checks that two strings are equal.
- format
proc
- Creates a string slice using interpolation of const expressions.
- from_
utf8 - Converts a byte string to a string slice
- hex
- Converts hexadecimal string slices to a byte array.
- ip_addr
- Converts a string slice to an IP address.
- is_
ascii - Checks if all characters in this (string) slice are within the ASCII range.
- join
- Concatenates string slices into a string slice, separated by a given separator.
- parse
- Parse a value from a string slice.
- raw_
cstr - Converts a string slice to
*const c_char
. - regex_
assert_ match regex
- Asserts that the string literal matches the pattern.
- repeat
- Creates a new string slice by repeating a string slice n times.
- replace
- Replaces all matches of a pattern with another string slice.
- sorted
- Sorts string slices and returns a new array.
- split
- Returns an array of substrings of a string slice, separated by characters matched by a pattern.
- split_
inclusive - Returns an array of substrings of a string slice, separated by characters matched by a pattern.
- split_
lines - Returns an array of the lines in a string.
- squish
- Splits the string by ASCII whitespaces, and then joins the parts with a single space.
- starts_
with - Returns
true
if the given pattern matches a prefix of this string slice. - strip_
prefix - Returns a string slice with the prefix removed.
- strip_
suffix - Returns a string slice with the suffix removed.
- to_
byte_ array - Converts a string slice or a byte string to a byte array.
- to_
char_ array - Converts a string slice into an array of its characters.
- to_str
- Converts a value to a string slice.
- unwrap
- Unwraps a container, returns the content.
- verified_
header_ name http
- Returns a compile-time verified header name string literal.
- verified_
regex regex
- Returns a compile-time verified regex string literal.