UseFieldRef
The foundational field getter that borrows a field through AsRef/AsMut, for the case where the
stored type differs from the getter's return type.
Overview
Under Context-Generic Programming (CGP), a context chooses the provider behind each getter
call, and UseFieldRef<Tag, Value> reads the field named by Tag from the
context (the type the method runs on, which supplies the
values it needs as its fields) and borrows it through AsRef to produce a &Value, where the
stored field type implements AsRef<Value>. It exists for a getter whose return type is reached
through a field rather than being the field's own type: a &Config from a stored Arc<Config>,
for example, where the field is not a Config but can be borrowed as one.
UseFieldRef is a foundational FieldGetter rather than a getter
component's own provider, so it is wired through its WithFieldRef alias,
WithProvider<UseFieldRef<Tag, Value>>. That distinguishes it from UseField, which
#[cgp_getter] generates a getter-component implementation for directly.
Most borrowed-view getters do not need UseFieldRef at all, and this is the key thing to know
before reaching for it. When a getter's return type is one of the shorthands the getter macros
recognize, the generated UseField implementation already borrows for you: a &str
getter reads a String field through AsRef::as_ref, a &[T] getter reads any 'static field
implementing AsRef<[T]>, such as a Vec<u8>, through AsRef::as_ref, and an Option<&T> or
Option<&str> getter reads an Option<T> or Option<String> field. Each is wired with a plain
UseField. UseFieldRef is for the remaining case, a getter that returns &T for some type T
the field is not stored as but can be borrowed as. Like every CGP provider, it carries no runtime
value.
Usage
UseFieldRef supplies only the foundational FieldGetter, so it is wired
through its WithFieldRef alias rather than named directly. See
WithFieldRef for the import, the wiring form, and a worked example; the mechanism
those rest on is described under Under the hood below.
When to use it
You choose UseFieldRef by wiring its WithFieldRef alias, so the guidance on
when a borrowed-view getter needs it, rather than the plain UseField or an
#[implicit] argument, lives with that alias, on
WithFieldRef.
Under the hood
UseFieldRef<Tag, Value> implements the provider-side getter
FieldGetter by reading the field at Tag and dereferencing it to
&Value:
impl<Context, OutTag, Tag, Value> FieldGetter<Context, OutTag> for UseFieldRef<Tag, Value>
where
Context: HasField<Tag, Value: AsRef<Value> + 'static>,
{
type Value = Value;
fn get_field(context: &Context, _tag: PhantomData<OutTag>) -> &Value {
context.get_field(PhantomData).as_ref()
}
}
The where clause carries the defining constraint: the context's field at Tag must implement
AsRef<Value>, so the stored type can be borrowed as the exposed type. As in
UseField, OutTag is the tag the component asks under and is ignored, while the
field is read at Tag. The body reads the field and calls as_ref(). The stored field type must
also be 'static, so a field holding a borrowed reference cannot be read this way.
UseFieldRef also implements the mutable getter MutFieldGetter,
requiring the field type to implement both AsRef<Value> and AsMut<Value> and to be 'static,
and returning &mut Value through as_mut(). Because these are FieldGetter implementations rather than a getter component's own
provider trait, the WithProvider adapter behind WithFieldRef turns
UseFieldRef into a provider a getter component can be wired to. Unlike UseField, it
does not implement TypeProvider, because its purpose is borrowed field
access rather than abstract-type resolution.
Related constructs
UseField— the getter provider that reads a field directly, and that already handles the&str/&[u8]borrowed shorthands.WithFieldRef— the alias you wire, and the home of the import and worked example.WithProvider— the adapter behind theWithFieldRefalias, which turnsUseFieldRefinto a getter-component provider.ChainGetters— another foundationalFieldGetter, composed for nested contexts.#[cgp_getter]— the macro that defines the getter this is wired to.FieldGetterandMutFieldGetter— the provider-side getters it implements, overHasField.
The ideas behind it:
- Impl-side dependencies — value injection through a provider's own requirements, of which a getter is one form.
Source
- Struct,
WithFieldRefalias, and theFieldGetter/MutFieldGetterimpls:use_ref.rs - The traits it implements:
has_field.rsandhas_field_mut.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.