ToFieldsRef
Walking a value's shape without consuming it.
Overview
In Context-Generic Programming (CGP), ToFields takes a value apart
into its shape and consumes it in the process. Code
that only reads (a validator, a serializer, a routine that inspects a struct and hands it back)
should not have to. ToFieldsRef produces the borrowed shape instead. The original survives,
and every entry in the result holds a reference rather than a value.
It is the weaker requirement, so prefer it wherever it suffices. Bounding on
ToFields when a borrow would do forces every caller to give up ownership or
clone, which is the most common over-requirement in this family.
Definition
ToFieldsRef adds one borrowing method to the borrowed-shape trait it extends:
pub trait ToFieldsRef: HasFieldsRef {
fn to_fields_ref<'a>(&'a self) -> Self::FieldsRef<'a>
where
Self: 'a;
}
It supertraits HasFieldsRef rather
than HasFields, which is the one structural difference from its owning
counterpart ToFields: the borrowed shape and the owned shape are named by two
independent traits, and each conversion supertraits the one it produces. The method borrows self
for 'a and returns the borrowed FieldsRef<'a> shape at that lifetime, so
the original stays intact, and the where Self: 'a clause keeps the borrowed shape from outliving
the value.
Usage
It is not in the prelude. Import it from cgp::core::field::traits.
The impls come from #[derive(HasFields)], which emits all
five shape traits together.
Examples
Reading one entry of a value's borrowed shape, and using the value afterwards:
use cgp::core::field::traits::ToFieldsRef;
use cgp::prelude::*;
#[derive(HasFields)]
pub struct Config {
pub host: String,
pub port: u16,
}
pub fn host_of(config: &Config) -> &String {
config.to_fields_ref().0.value
}
pub fn demo() {
let config = Config {
host: "localhost".to_owned(),
port: 8080,
};
assert_eq!(host_of(&config), "localhost");
assert_eq!(config.port, 8080); // `config` is still usable
}
to_fields_ref().0 is the first entry, and its value is a &String borrowed from config, which
stays usable.
When to use it
Bound on it whenever generic code reads a shape and the caller keeps the value. This is most read-only structural code.
ToFieldswhen the code genuinely consumes: a conversion, a merge, a rebuild.FromFieldsfor constructing a value, which has no borrowing counterpart: a borrowed shape cannot yield an owned value.HasFieldsRefalone when the code only names the borrowed shape.HasFieldwhen one named field is all that is wanted.
There is one thing this cannot do that ToFields can: hand the entries' values
onward by ownership. A routine that must move a field out of a struct needs the owning form.
Under the hood
The generated impl borrows each field and converts the borrow into the entry of the borrowed shape,
under the reserved lifetime name '__a that HasFieldsRef
declares. cargo cgp expand on the example's Config shows:
impl ToFieldsRef for Config {
fn to_fields_ref<'__a>(&'__a self) -> <Self as HasFieldsRef>::FieldsRef<'__a>
where
Self: '__a,
{
Cons((&self.host).into(), Cons((&self.port).into(), Nil))
}
}
The where Self: 'a clause on both the trait method and the associated type keeps the result
tied to the borrow it came from, so the shape cannot outlive the value.
One consequence follows from the rewrite being per-entry rather than structural: a field that is
already a reference gains another one, appearing as &'__a &'a Name. That is correct, and it is
the detail most likely to look wrong in an error message.
An enum's borrowed conversion matches the concrete variant and produces the corresponding arm of the
borrowed sum, with the payload borrowed rather than moved, which is also how
HasExtractorRef reads a variant without consuming the value.
Common Mistakes
It supertraits HasFieldsRef, not HasFields.
Bounding on ToFieldsRef does not give you Fields; require both traits if the code needs both
shapes.
A field that is already borrowed gets a second borrow in the result, which is correct and surprising.
There is no FromFieldsRef. The borrowed half of the family is read-only by construction.
The lifetime usually has to be spelled out. A signature that returns or stores FieldsRef<'a>
inherits the where Self: 'a clause and rarely elides cleanly.
A newtype's borrowed shape is a borrow of the inner type, not a one-element product. It is the same special case the owned shape has.
Related constructs
HasFieldsRef: the supertrait that names the borrowed shape.ToFields: the owning counterpart, which consumes the value.FromFields: rebuilding a value, which has no borrowing form.HasFields: the owned shape, and where the family is explained in full.#[derive(HasFields)]: generates this impl.HasExtractorRef: the same borrow-rather-than-consume idea on the enum side.Field: one entry of a shape.
The ideas behind it:
- Extensible records: a struct as a product of named fields.
Source
to_fields.rs:ToFieldsRefandToFields
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.