Skip to main content

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 Chars chain by reading off the characters. An error that mentions HasField<Symbol<5, Chars<'w', Chars<'i', ...>>>> says that the field width is 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 Index for 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.

  • Nil: the end marker that terminates a Chars chain.
  • Cons: the general product list this one specializes, with a type head rather than a const char.
  • Symbol!: the macro that folds a string into a Chars chain and wraps it.
  • StaticFormat and StaticString: recover the runtime string and the const from the chain.
  • HasField: matches a field against its Symbol! tag.
  • Field: carries a Symbol! tag beside its value.
  • Index: the position tag for a tuple field, the numeric counterpart.

The ideas behind it:

Source​


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.