Chars
One character of a type-level string: the list that spells a field name out one character at a time so the name can be a type.
Overview
In Context-Generic Programming (CGP), Chars<const CHAR: char, Tail> encodes a string as
a type, so that a field name can take part in trait resolution. CGP keys field access by a tag type. To read a field called name, something must stand for
the string "name" at the type level, so that the compiler can tell one
HasField impl from another by the tag alone. A Chars chain
turns the string into a type, and a Symbol that wraps the chain is the tag itself.
The encoding is a list of characters because of a limit in stable Rust. A String or &str cannot be
a const-generic parameter, but a single char can. So CGP spells the string out one character at a time
through a recursive Chars list terminated by Nil, in the same way the product list spells
out its elements through Cons. Chars is the specialized form of Cons whose head is a
const char rather than a type.
You write this through Symbol! rather than directly. Symbol!("abc") folds
into Symbol<3, Chars<'a', Chars<'b', Chars<'c', Nil>>>>. That macro's page covers the fold, the
byte-length parameter, and the rest of the wrapper. This page covers the Chars type underneath.
Definition
Chars is a zero-sized struct carrying one character as a const parameter and the rest of the string as
its tail:
#[derive(Eq, PartialEq, Clone, Copy, Default)]
pub struct Chars<const CHAR: char, Tail>(pub PhantomData<Tail>);
CHAR is the character at this position, and Tail is the rest of the string, which is the next
Chars node or Nil at the end. The character lives in the const parameter, and the tail
lives in a PhantomData<Tail>, so a Chars chain does not carry runtime data
and compiles to a zero-sized value. A Symbol<const LEN: usize, Chars> then wraps such a chain
together with the string's byte length. The wrapper stores the length explicitly because stable Rust
cannot compute it inside a const-generic context, and the Symbol! page
explains why. Neither type is in the prelude, since the macro writes them for you; import both from
cgp::core::field::types when you name one.
Behavior
A Chars chain reconstructs its original string on demand through the
StaticFormat trait, which formats a type-level string
into a Formatter without needing a value. Chars<CHAR, Tail> writes CHAR and then recurses into
the tail, and Nil ends the recursion by writing nothing. A Symbol forwards to its
inner Chars, and the Display impls on both defer to StaticFormat, so
<Symbol!("hello")>::default().to_string() yields "hello".
The length a Symbol records enables StaticString, which
exposes the string as a const VALUE: &'static str rather than as a formatting routine. It decodes
the characters into a byte buffer sized by that length at compile time. A bare Chars chain lacks
the length, so StaticString is implemented for Symbol and for Nil, not for Chars. Code that
needs the string at run time uses Display, and code that needs it as a const uses StaticString.
Examples
A type-level string most often appears as the tag in a
HasField bound, where it names the field a function or
provider reads. The same type rebuilds its string through Display:
use cgp::core::field::traits::HasField;
use cgp::core::field::types::{Chars, Nil, Symbol};
use cgp::prelude::*;
// The tag names the field the function reads.
pub fn name_of<Context>(context: &Context) -> &str
where
Context: HasField<Symbol!("name"), Value = String>,
{
context.get_field(PhantomData::<Symbol!("name")>)
}
#[derive(HasField)]
pub struct Person {
pub name: String,
}
pub fn demo() {
let person = Person {
name: "Alice".to_owned(),
};
assert_eq!(name_of(&person), "Alice");
// `Symbol!` spells the string out as a `Chars` chain, with its byte length in front.
let _: PhantomData<Symbol<3, Chars<'a', Chars<'b', Chars<'c', Nil>>>>> =
PhantomData::<Symbol!("abc")>;
let _: PhantomData<Symbol<6, Chars<'世', Chars<'界', Nil>>>> = PhantomData::<Symbol!("世界")>;
// `Display` walks the chain to rebuild the text.
let symbol = <Symbol!("hello")>::default();
assert_eq!(symbol.to_string(), "hello");
assert_eq!(core::mem::size_of::<Symbol!("hello")>(), 0);
}
The two PhantomData annotations are the check on the expansion: "世界" records a length of 6,
its UTF-8 byte count, over a chain of two Chars nodes. Because the encoding is a list, an empty
string is Symbol<0, Nil>: a Symbol whose character list is only the terminator.
When to use it
You read Chars in an error, and you write Symbol!. The macro produces the
chain. You need to know the type so that you can decode a field name in a diagnostic.
- Decode a
Charschain by reading off the characters. An error that mentionsHasField<Symbol<5, Chars<'w', Chars<'i', ...>>>>says that the fieldwidthis involved. - Use
Symbol!for a field-name tag, and let the ergonomic constructs produce it from an argument or a method name where they can. - Use
Indexfor a tuple-field position, which encodes a number rather than a string.
Common Mistakes
A missing field appears in a raw error as a Chars chain. A provider that reads width and
height, wired on a context with only height, fails its check:
#[cgp_component(AreaCalculator)]
pub trait CanCalculateArea {
fn area(&self) -> f64;
}
#[cgp_impl(new RectangleArea)]
impl AreaCalculator {
fn area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}
}
#[derive(HasField)]
pub struct Rectangle {
pub height: f64,
}
delegate_components! {
Rectangle {
AreaCalculatorComponent: RectangleArea,
}
}
check_components! {
Rectangle {
AreaCalculatorComponent,
}
}
The compiler's help line names the missing tag, and the tag the context does have, character by character:
help: the trait `HasField<Symbol<5, Chars<'w', Chars<'i', Chars<'d', Chars<'t', Chars<'h', Nil>>>>>>>` is not implemented for `Rectangle`
but trait `HasField<Symbol<6, Chars<'h', Chars<'e', Chars<'i', Chars<'g', Chars<'h', cgp::macro_prelude::Chars<'t', Nil>>>>>>>>` is implemented for it
cargo cgp check reads the chain back into the name, and reports
[CGP-E110] missing field `width` on `Rectangle` as the root cause. cargo cgp check leads with
the root cause for the classes it recognizes, and the tool does not yet reshape every class.
The LEN in a wrapping Symbol is bytes, not characters. For ASCII the two counts agree, so the
difference shows only on a non-ASCII field name. There LEN does not match the visible character count,
and the Chars chain is shorter than LEN.
Chars is zero-sized, so it does not hold a string at run time. The Display impl rebuilds the text
from the type, and the value does not store a &str.
A Chars chain is the character specialization of Cons, not a general list. Its head is
a const char, so it cannot carry arbitrary element types the way a product list does.
Related constructs
Nil: the end marker that terminates aCharschain.Cons: the general product list this one specializes, with a type head rather than aconst char.Symbol!: the macro that folds a string into aCharschain and wraps it.StaticFormatandStaticString: recover the runtime string and the const from the chain.HasField: matches a field against itsSymbol!tag.Field: carries aSymbol!tag beside its value.Index: the position tag for a tuple field, the numeric counterpart.
The ideas behind it:
- Extensible records: where field-name tags are used at scale.
Source
- The type:
chars.rs, with theSymbolwrapper insymbol.rsandNilinnil.rs - The
StaticFormatimpls behindDisplay:static_format.rs, and the const-decodingStaticString:static_string.rs - The constructing macro is
Symbol!.
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.