AppendProduct
Adding one entry to the end of a type-level product list.
Overview
A struct's shape in Context-Generic Programming (CGP) is
a type-level list, a Product! of named fields. Code that processes such
a shape generically sometimes needs to describe a new shape computed from an old one: the shape a
routine promises to return after adding a field, say, or a bound relating an input shape to an
output one.
AppendProduct<Item> is that computation for a single entry. It takes a product and an item and names
the product with that item added at the end.
This is one of the least user-facing traits in the reference, and CGP itself never uses it. It is provided for generic code of your own that computes shapes, and you meet it only there or in an error message from such code.
Definition
AppendProduct is parameterized by the item to add and exposes the extended list as an associated type:
pub trait AppendProduct<Item: ?Sized> {
type Output;
}
Self is the existing product, Item is the entry to add, and Output is the resulting product.
Item may be unsized. The trait lacks a method, because nothing needs executing: Output is an
associated type the trait solver evaluates while the compiler type-checks, so it costs nothing at
run time.
Usage
It is not in the prelude. Import it from cgp::core::field::traits:
use cgp::core::field::traits::AppendProduct;
Every existing entry is preserved in order, and the new one lands last. Appending onto Nil (the empty
product) yields a one-element list, which is the recursion's base case and occasionally useful to know
when reading a bound.
Examples
The results are types, so the check is a type equality: each function compiles only if the computed
Output is the type it is returned as.
use cgp::core::field::traits::AppendProduct;
use cgp::core::field::types::{Field, Nil};
use cgp::prelude::*;
pub type Base = Product![Field<Symbol!("host"), String>];
pub type WithPort = <Base as AppendProduct<Field<Symbol!("port"), u16>>>::Output;
/// The page's claim about `WithPort`.
pub fn assert_with_port(
fields: WithPort,
) -> Product![Field<Symbol!("host"), String>, Field<Symbol!("port"), u16>] {
fields
}
/// A generic signature naming the shape a routine will produce.
pub fn with_extra_field<Fields, Extra>() -> PhantomData<<Fields as AppendProduct<Extra>>::Output>
where
Fields: AppendProduct<Extra>,
{
PhantomData
}
/// The base case the page states under *Using it*: appending onto `Nil` yields a one-element list.
pub fn assert_nil_base_case(
fields: <Nil as AppendProduct<Field<Symbol!("host"), String>>>::Output,
) -> Base {
fields
}
with_extra_field is the generic form: its return type names the shape the routine promises,
computed from its parameters.
When to use it
Reach for it when a routine must describe the shape it will produce (in a signature, an
associated type, or a where clause) and essentially never otherwise. Nothing in CGP names it, so
it matters only to code of your own that computes shapes.
- Reach for
ConcatProductto splice a whole list rather than one entry. Append is its single-entry special case, so if you find yourself appending in a loop, you wanted concat. - Use
HasFieldsinstead if you only need a type's existing shape. This trait computes new shapes; it is not how you obtain one. - Use the builder or extractor family instead if you are moving values through a shape. This never touches a value, so if you want something to happen at run time, it is the wrong layer.
AppendSum does not exist. Growing a sum is not an operation this layer provides.
Under the hood
The trait is a pair of impls, one for the list's Cons node and one for its Nil terminator. Each head
is kept and the tail rebuilt, with a single-element list grafted on at the end:
impl<Item> AppendProduct<Item> for Nil {
type Output = Cons<Item, Nil>;
}
impl<Head, Tail, Item> AppendProduct<Item> for Cons<Head, Tail>
where
Tail: AppendProduct<Item>,
{
type Output = Cons<Head, Tail::Output>;
}
Because the recursion only ever rebuilds the list, order is structurally preserved, which is why appending yields a different type from prepending, and why two products with the same entries in different orders are unrelated types.
All of this is resolved during type checking. Neither impl contains a fn.
Common Mistakes
It is not in the prelude. Import from cgp::core::field::traits. This is the first thing that goes
wrong when reaching for it.
The result is Output, while MapFields exposes Mapped. The asymmetry between
the three product operations is easy to forget, and reaching for the wrong name is a plain
unresolved-associated-type error.
It is product-only. It lacks a sum equivalent.
Order is part of the type. Appending is not commutative with prepending, and nothing reorders a list to make two shapes match.
A long list means a deep recursion. This is trait resolution over the list, so a very wide shape costs compile time proportional to its width, as every type-level list recursion in CGP does.
Related constructs
ConcatProduct: the general form; append is its single-entry case.MapFields: rewriting every entry rather than adding one.Product!: the sugar for the lists this operates on.- Type-level lists: the
Cons/Nilchain underneath. HasFields: where a type's existing shape comes from.Field: the entries a field list is usually made of.HasBuilder: the family that moves values through the shapes this computes.
The ideas behind it:
- Extensible records: where computing a new shape is put to work.
Source
append_product.rs:AppendProduct
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.