StaticString
Recovering a type-level string as a compile-time &'static str.
Overview
Context-Generic Programming (CGP) encodes field and variant names as types (a
Symbol! is a length plus a character list, one node per character) so
that names can drive trait resolution. But a program eventually needs those names as ordinary
strings: to report a missing field, to build a key, to compare against input.
StaticString is how a name comes back out, and it does it eagerly.
This is the recovery trait to reach for. Its sibling
StaticFormat recovers a name lazily by writing into a formatter, which backs
Display; reach for it only where a value to format is missing and a constant will not do.
Definition
StaticString carries a single associated constant and nothing else:
pub trait StaticString {
const VALUE: &'static str;
}
VALUE is the decoded string as a constant, computed by const evaluation rather than at run time,
so the string is available wherever a const is, costs nothing per use, and can be compared or
stored freely. The trait is implemented for the type-level string itself and lacks a method, because
there is nothing to call one on.
Usage
It is not in the prelude. Import it from cgp::core::field::traits:
use cgp::core::field::traits::StaticString;
VALUE is an associated constant rather than a method, so it is named through the trait:
<Symbol!("name") as StaticString>::VALUE. Nothing needs a value or a call.
Every Symbol! has it, including the empty one, and so does Nil, whose
value is "". A bare Chars list does not, because the impl needs the byte
length only Symbol carries; Common Mistakes shows the error.
Examples
Decoding a symbol eagerly and lazily, multi-byte and empty symbols, and a generic routine naming its tag:
use cgp::prelude::*;
use cgp::core::field::traits::StaticString;
// A generic routine recovers the name of whatever tag it is given.
pub fn field_name<Tag: StaticString>(_tag: PhantomData<Tag>) -> &'static str {
Tag::VALUE
}
pub fn demo() {
// eagerly, as a compile-time constant
assert_eq!(<Symbol!("hello") as StaticString>::VALUE, "hello");
// lazily, through `Display`: reconstructed at the point of formatting
let s = <Symbol!("hello")>::default();
assert_eq!(s.to_string(), "hello");
assert_eq!(<Symbol!("世界你好") as StaticString>::VALUE, "世界你好");
assert_eq!(<Symbol!("") as StaticString>::VALUE, "");
assert_eq!(field_name(PhantomData::<Symbol!("height")>), "height");
}
Multi-byte Unicode round-trips faithfully and the empty symbol decodes to the empty string.
field_name is where the trait shows up in real code: the optional-field
layer's finalize_optional reports a missing field by returning
Tag::VALUE, the field's own name as a static string, with no allocation.
When to use it
Reach for StaticString when you need a name as data, and for Display when you need it in a
message. That is the whole decision.
StaticStringfor a constant, a key, a comparison, or anywhere the name is used more than once. It is computed at compile time, so it costs nothing per call.Display/to_string()for one-off formatting, which is whatStaticFormatpowers. Bounding on that trait directly is for the narrow case where a value to format is missing.ConcatPathwhen the thing being composed is a path rather than a string.
Two things this is not for. It is not a general string facility: Symbol!
exists to key field and variant lookups, and building programs out of type-level strings is not what the
encoding is for. And it is not how you read a field: recovering a name tells you what a field is
called, while HasField reads its value.
Under the hood
StaticString is const evaluation rather than a recursion at run time. It is a blanket impl over a
private StaticBytes trait, which only Symbol<LEN, Chars> and Nil implement:
impl<T> StaticString for T
where
T: StaticBytes,
{
const VALUE: &'static str = const {
match str::from_utf8(T::BYTES) {
Ok(value) => value,
Err(_) => panic!("error const decoding &[u8] to &str"),
}
};
}
Symbol<LEN, Chars>'s BYTES is a [u8; LEN] computed in a const fn by walking the character
list and UTF-8-encoding each character into the array, and VALUE then validates those bytes as
UTF-8 and exposes the &'static str.
That array is why Symbol carries a LEN at all. A const-evaluated array's length must be a
constant known from the type, and stable Rust cannot compute it from the character list inside a
generic, so the macro precomputes it. It is a byte length, which makes multi-byte Unicode
round-trip correctly and makes LEN disagree with the visible character count for any non-ASCII
name.
Common Mistakes
It is not in the prelude, and its module differs from its neighbours'. Import StaticString
from cgp::core::field::traits; ConcatPath and
StaticFormat come from cgp::core::base::traits.
VALUE is a constant, so it is named through the trait. Write
<Symbol!("name") as StaticString>::VALUE; the trait lacks a method.
LEN on a Symbol is bytes, not characters. They coincide for ASCII, so the distinction only
surfaces on a non-ASCII name, where the number will not match the visible character count.
Display reconstructs the string rather than reading a stored one. A Symbol does not store a
&str, so to_string() walks the type. For a name used repeatedly, VALUE is the cheaper choice.
It decodes a symbol, not a path or a bare character list. A Path! is a
list of segments; decoding one means decoding each segment's symbol. And a Chars list on its own,
without the Symbol wrapper that carries its byte length, lacks the impl:
pub const NAME: &str = <Chars<'a', Nil> as StaticString>::VALUE;
error[E0277]: the trait bound `cgp::macro_prelude::Chars<'a', Nil>: StaticString` is not satisfied
...
| ^^^^^^^^^^^^^^^ the trait `cgp::cgp_core::cgp_field::traits::static_string::StaticBytes` is not implemented for `cgp::macro_prelude::Chars<'a', Nil>`
Related constructs
StaticFormat: the lazy counterpart, behind theDisplayimpls.ConcatPath: the same recovery idea one level up, for paths.Symbol!: the type-level string this decodes, and where theLENcomes from.- Type-level lists: the
Charschain being walked. HasField: where the names being decoded are used as keys.FinalizeOptional: a real consumer, reporting a missing field by name.
The ideas behind it:
- Extensible records: where field-name types are put to work at scale.
Source
static_string.rs:StaticStringand its const-evaluated UTF-8 decoding
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.