Field
A value paired with its type-level name tag, so a struct's fields and an enum's variants can be described one entry at a time without naming the concrete type.
Overview
In Context-Generic Programming (CGP), Field<Tag, Value> carries a field's name and its
value together in one type. A bare
Product! list such as Product![String, u8] records the value types and their
order, but it cannot tell name: String from any other String. Wrapping each element in a Field,
as Field<Symbol!("name"), String>, attaches the name as a type, so a struct's shape describes itself.
Code that walks the list matches on the tag to find the field it wants.
The name is a type because the program needs it only at compile time, for trait resolution and
dispatch, and never at run time. A Field<Tag, Value> is exactly as large as its Value, because
the tag lives in a zero-sized PhantomData<Tag>. So naming a field this way
costs nothing at run time and makes field-by-field generic code possible.
Symbol! provides the same type-as-name encoding for a named field, and
Index provides it for a tuple position. Field joins that tag to the value it
labels.
Field fills both structural lists. In a record it is the element of a Product!
of entries, one per field. In a variant it is the element of a Sum! of entries, one
per variant, where the Value is the variant's payload. The same Field<Tag, Value> shape names a
field in a struct and a variant in an enum.
Definition
Field holds the value alongside a phantom tag:
pub struct Field<Tag, Value> {
pub value: Value,
pub phantom: PhantomData<Tag>,
}
Tag is the type-level name of the field. It appears only inside PhantomData<Tag>, never in a
stored field. It is usually a type-level string such
as Symbol!("name") for a named field, or a type-level number such as Index<0> for a tuple
position. Value is the field's actual type, and value is the only data the struct keeps. Apart
from the tag, a Field is a thin wrapper around its Value. It is not in the prelude, so import it
from cgp::core::field::types.
Behavior
You build a Field from a value without a tag argument, because the tag comes from the target type
rather than from you. The From<Value> impl fills in value and sets phantom to PhantomData. So
let f: Field<Symbol!("name"), String> = "Alice".to_string().into(); compiles, and the compiler infers
the tag from the expected type. This is why generated code builds each entry with a plain .into().
The other trait impls defer to the value and ignore the tag, so a Field behaves like its Value
for comparison and printing. Debug forwards to the value's Debug and does not show the tag.
PartialEq and Eq compare only value, each gated on the matching bound on Value. Two Field
values are equal when their values are equal. The tag is a compile-time matter and does not take
part at run time. Field implements nothing else: it is not Clone, Copy, or Default, whatever
its Value is.
Because the tag lives only in PhantomData, code that needs the name reads it from the Tag parameter
through trait resolution rather than from stored data. For example, it matches a
Field<Symbol!("name"), _> against a HasField<Symbol!("name")>
bound.
A tuple struct with exactly one field is the exception to the wrapping. Its shape is the field's
type itself, without a Field around it or a list, so struct Meters(u32) has Fields = u32. A
tuple struct with two or more fields tags each entry by position, as Field<Index<0>, u32>. Inside
an enum, a variant with a single unnamed field has that field's type as its payload in the variant's
Field.
Examples
A struct's shape, as #[derive(HasFields)] assigns it, is a list
of Field entries, and to_fields turns a value into that list:
use cgp::core::field::traits::ToFields;
use cgp::core::field::types::{Cons, Field, Index, Nil};
use cgp::prelude::*;
#[derive(HasFields)]
pub struct Person {
pub name: String,
pub age: u8,
}
#[derive(HasFields)]
pub struct Point(pub u32, pub u32);
#[derive(HasFields)]
pub struct Meters(pub u32);
pub fn demo() {
// A struct's shape is a list of `Field` entries, each tagged by its name.
let fields: Product![Field<Symbol!("name"), String>, Field<Symbol!("age"), u8>] = Person {
name: "Alice".to_owned(),
age: 30,
}
.to_fields();
let Cons(name, Cons(age, Nil)) = fields;
assert_eq!(name.value, "Alice");
assert_eq!(age.value, 30);
// A tuple struct's entries are tagged by position.
let Cons(x, Cons(y, Nil)): Product![Field<Index<0>, u32>, Field<Index<1>, u32>] =
Point(3, 4).to_fields();
assert_eq!((x.value, y.value), (3, 4));
// A one-field tuple struct's shape is the field's type itself.
let inner: u32 = Meters(7).to_fields();
assert_eq!(inner, 7);
// One entry, built from its value; the annotation supplies the tag.
let entry: Field<Symbol!("name"), String> = "Bob".to_owned().into();
assert_eq!(entry.value, "Bob");
// The tag adds no size, and `Debug` prints the value alone.
assert_eq!(
core::mem::size_of::<Field<Symbol!("name"), String>>(),
core::mem::size_of::<String>()
);
assert_eq!(format!("{entry:?}"), "\"Bob\"");
}
The annotations on fields and on the tuple pattern are the check: each names the list type the
derive assigned, and the program compiles only if it matches. The derive writes that list as
type Fields = Product![Field<Symbol!("name"), String>, Field<Symbol!("age"), u8>]; for Person,
and as type Fields = u32; for Meters.
When to use it
You read Field far more often than you write it. The common case is to recognize it in a generated
shape or in an error, and this page is mostly for that.
- Let the derives build it.
#[derive(HasFields)]and#[derive(CgpData)]produce theFieldentries of a type's shape, so a type you own gets its entries from one derive rather than from a list you write yourself. - Construct a
Fielddirectly only in generic shape code of your own, where you assemble or rewrite a record or a variant entry by entry. Build one with.into(), and let the expected type supply the tag. - Do not use a bare
Product!of values when you need the names. A list ofFieldentries carries the names, and the operations that walk a shape match on them.
Common Mistakes
The tag is compile-time only, so it never affects equality or printing. Two Field values compare
equal when their values are equal, and Debug shows the value alone. The tag does not distinguish them at
run time. It distinguishes them only in the type.
A Field is the size of its Value, not larger. The tag occupies zero bytes, so wrapping a value in
a Field is free at run time.
A one-field tuple struct's shape lacks a Field. Code that expects every shape to be a list of
Field entries meets a bare u32 for struct Meters(u32), since the derive treats such a struct
as a newtype around its field.
The tag must match exactly for a lookup to resolve. Field<Symbol!("first_name"), _> and
Field<Symbol!("firstName"), _> carry unrelated tags, so a name mismatch appears as an unsatisfied
HasField bound rather than as a typo.
Related constructs
Symbol!: the tag for a named field or variant.Index: the tag for a tuple-struct position.PhantomData: where the tag is stored, at zero size.Product!andSum!: the lists ofFieldentries that describe a record and a variant.Struct!andEnum!: write a list ofFieldentries as the body of a struct or enum declaration, each tag taken from a field or variant name.ConsandEither: the product and sum lists those entries are built into.HasFields: exposes a type's whole list ofFieldentries.HasField: single-field access against a matching tag.#[derive(HasFields)]: assigns the list of entries to a type.
The ideas behind it:
- Extensible records: where field-name entries are used at scale.
- Extensible variants: the same entry naming a variant.
Source
- The type and its
From,Debug,PartialEq, andEqimpls:field.rs - Consumed by the field machinery:
has_fields.rs, with rebuilding infrom_fields.rsandto_fields.rs - The derive that emits
Product!/Sum!lists of entries:derive_has_fields/
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.