Skip to main content

Index

A number lifted into a type, so a tuple-struct field can be named by its position the way Symbol! names a field by its string.

Overview​

In Context-Generic Programming (CGP), Index<const I: usize> encodes a usize at the type level. CGP's getter mechanism keys every field by a type tag, but a tuple-struct field has only a position and lacks a string name to turn into a Symbol!. So the position itself becomes a type, and positional fields can use the same trait-resolution machinery as named fields. Index<I> is that type. It carries a usize as a const parameter and nothing else, so Index<0>, Index<1>, and Index<2> are distinct types that stand for a tuple struct's positional fields.

Encoding the position as a type lets positional field access resolve through traits. Here a context is the type the method runs on, which supplies the values it needs as its fields. Because Index<0> is a type, a context can carry a HasField<Index<0>> impl for its first field and a HasField<Index<1>> impl for its second, side by side. The compiler selects the right one from the tag alone, as it does for differently named Symbol! tags. Index is the numeric counterpart to Symbol!. A field is keyed by a Symbol! when it has a name, and by an Index when it has only a position.

Index is a zero-sized marker without runtime data. Its only job is to make a number available at the type level. So it can serve as a HasField tag, as the tag of a Field entry inside a tuple struct's shape, and as the type inside a PhantomData wherever compile-time code needs a positional name.

Definition​

Index is a zero-sized struct parameterized only by a const usize:

#[derive(Eq, PartialEq, Clone, Copy, Default)]
pub struct Index<const I: usize>;

I is the position the type represents: Index<0> for the field at offset zero, and so on. The struct is empty, so a value of Index<I> holds nothing, and the number lives entirely in the type. The derived Default, Clone, and Copy make a value available whenever code needs one. Eq and PartialEq treat any two values of the same Index<I> as equal, because they hold nothing. Index<I> also implements Display and Debug, and both print the underlying number. So Index<0> displays as 0, and output and diagnostics show the position a tag stands for. It is not in the prelude, so import it from cgp::core::field::types.

Behavior​

A tuple struct keys each of its fields by Index<N>, counting from zero, so code reads the field at position N through the tag Index<N>. When a tuple struct derives #[derive(HasField)], the generated impls use Index<0> for the .0 field, Index<1> for .1, and so on, with a HasFieldMut impl beside each HasField one. Each get_field(PhantomData::<Index<N>>) call maps to the matching positional access.

The same tags name the entries of a tuple struct's HasFields shape when it has two or more fields, a list of Field<Index<N>, _> entries. So generic code that walks the field list reads positions where it would read Symbol! names for a named struct. A tuple struct with exactly one field is the exception: its shape is the field's type itself, without a Field<Index<0>, _> around it, although its HasField<Index<0>> impl still exists.

Because Index<I> is zero-sized and the position lives in the type, a field access by index resolves entirely at compile time. The access does not check an array bound and does not index at run time. Selecting the wrong index is a type error rather than a panic, because a three-field struct lacks a HasField impl for Index<5>.

Examples​

A tuple struct that derives HasField is read by position, and an Index prints the number it stands for:

use cgp::core::field::traits::HasField;
use cgp::core::field::types::Index;
use cgp::prelude::*;

#[derive(HasField)]
pub struct Pair(pub u32, pub String);

pub fn demo() {
let pair = Pair(7, "hi".to_owned());

assert_eq!(*pair.get_field(PhantomData::<Index<0>>), 7);
assert_eq!(pair.get_field(PhantomData::<Index<1>>), "hi");

// `Display` and `Debug` both print the number.
assert_eq!(Index::<2>.to_string(), "2");
assert_eq!(format!("{:?}", Index::<2>), "2");
}

The derive generates one impl pair per position. For the first field it writes:

impl HasField<Index<0>> for Pair {
type Value = u32;
fn get_field(&self, key: ::core::marker::PhantomData<Index<0>>) -> &Self::Value {
&self.0
}
}

and a matching HasFieldMut<Index<0>> impl returning &mut self.0.

When to use it​

Use Index for a tuple-field tag, and let the derive produce it where it can. The derive generates it for every field of a tuple struct that derives #[derive(HasField)], so you write it only when you tag a positional field yourself.

  • Use Symbol! for a named field, not an Index. Named and positional fields use different tags, and the derive generates the right one for each.
  • Write Index<N> for a tuple position, never a Symbol! of the number. Symbol!("0") is a string tag and does not match any field of a tuple struct.
  • Read Index<N> in an error as a position. A missing HasField<Index<2>> bound names the third field of a tuple struct.

Common Mistakes​

A position the struct lacks is a type error, not a panic. Reading Index<5> on a three-field tuple struct does not compile:

#[derive(HasField)]
pub struct Point(pub f64, pub f64, pub f64);

pub fn sixth(point: &Point) -> f64 {
*point.get_field(PhantomData::<Index<5>>)
}

The compiler reports error[E0277]: the trait bound `Point: cgp::macro_prelude::HasField<cgp::macro_prelude::Index<5>>` is not satisfied, and lists the three HasField<Index<0>> to HasField<Index<2>> impls the struct does have. Indices count from zero, as Rust's own .0 access does, so an off-by-one error surfaces the same way.

Index<N> and Symbol!("N") are different types. A tuple field is keyed by the number lifted into a type, not by a string of the digit, so Symbol!("0") never matches a tuple field and the derive never generates it. pair.get_field(PhantomData::<Symbol!("0")>) on the Pair above fails with error[E0277]: the trait bound `Pair: cgp::macro_prelude::HasField<cgp::macro_prelude::Symbol<1, cgp::macro_prelude::Chars<'0', Nil>>>` is not satisfied.

  • Symbol!: the string tag for a named field, the counterpart to this numeric one.
  • HasField: what a tag is looked up through.
  • #[derive(HasField)]: generates an Index tag per tuple field.
  • Field: carries an Index tag beside a positional value.
  • PhantomData: how an Index tag is passed to get_field.
  • HasFields: the tuple struct's shape whose entries this tag names.
  • Struct!: writes that shape as a tuple struct body, so Struct!(u64, String) keys its entries Index<0> and Index<1>.

The ideas behind it:

Source​

  • The type and its Display and Debug impls: index.rs
  • The #[derive(HasField)] codegen that tags tuple fields with Index<N>: cgp_data/, and the HasField trait it targets: has_field.rs

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.