Skip to main content

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.

  • 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 the WithFieldRef alias, which turns UseFieldRef into a getter-component provider.
  • ChainGetters — another foundational FieldGetter, composed for nested contexts.
  • #[cgp_getter] — the macro that defines the getter this is wired to.
  • FieldGetter and MutFieldGetter — the provider-side getters it implements, over HasField.

The ideas behind it:

  • Impl-side dependencies — value injection through a provider's own requirements, of which a getter is one form.

Source​


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.