Skip to main content

WithFieldRef

Wire a getter component to a field borrowed through AsRef, through the WithProvider adapter.

Overview​

Under Context-Generic Programming (CGP), a getter can borrow a field as another type, and WithFieldRef<Tag, Value> is the alias WithProvider<UseFieldRef<Tag, Value>>. It implements a getter component by reading the field named by Tag from the context, the type the method runs on, and borrowing it through AsRef to produce a &Value, where the stored field type implements AsRef<Value>. It adapts the foundational UseFieldRef getter through the WithProvider layer. Like every CGP provider, it carries no runtime value.

Unlike WithField, this alias is not an alternative to a directly-wireable provider: the bare UseFieldRef supplies only the foundational FieldGetter, so WithFieldRef is the form you wire.

Usage​

WithFieldRef is not in the prelude. Import it from cgp::core::field::impls. It takes the field tag and the borrowed value type, and appears as the value of a getter component's wiring entry:

use cgp::core::field::impls::WithFieldRef;

delegate_components! {
App {
ConfigGetterComponent: WithFieldRef<Symbol!("config"), Config>,
}
}

Tag names the field, as in UseField, and Value is the type the getter exposes. The stored field type must implement AsRef<Value> and be 'static (and, for the mutable getter, also AsMut<Value>), and the getter's return type must be &Value.

Examples​

A getter returns &Config while the context stores the config in a wrapper that borrows as Config. The wrapper implements AsRef<Config>, so WithFieldRef reads it and borrows through it:

use cgp::core::field::impls::WithFieldRef;
use cgp::prelude::*;

pub struct Config {
pub port: u16,
}

pub struct StoredConfig(pub Config);

impl AsRef<Config> for StoredConfig {
fn as_ref(&self) -> &Config {
&self.0
}
}

#[cgp_getter]
pub trait HasConfig {
fn config(&self) -> &Config;
}

#[derive(HasField)]
pub struct App {
pub config: StoredConfig,
}

delegate_components! {
App {
ConfigGetterComponent: WithFieldRef<Symbol!("config"), Config>,
}
}

check_components! {
App {
ConfigGetterComponent,
}
}

pub fn demo() {
let app = App { config: StoredConfig(Config { port: 8080 }) };
assert_eq!(app.config().port, 8080);
}

App wires ConfigGetterComponent to WithFieldRef<Symbol!("config"), Config>. The provider reads the config field, a StoredConfig, and because StoredConfig: AsRef<Config>, returns &Config from as_ref(). The getter exposes the borrowed Config view while the context owns the StoredConfig.

When to use it​

Reach for WithFieldRef when a getter returns &T and the context stores a different type that borrows as T through AsRef. The stored type and the exposed type differ, and neither the plain WithField nor an #[implicit] argument can bridge them.

The common borrowed-view getters need no WithFieldRef: a -> &str getter over a String field, a -> &[T] getter over a field implementing AsRef<[T]> such as a Vec<u8>, and an Option<&T> getter over an Option<T> field are all served by the plain UseField or WithField through the getter macros' return-type shorthands. For a field returned as its own type, an #[implicit] argument is simpler still.

Under the hood​

WithFieldRef<Tag, Value> is a type alias:

pub type WithFieldRef<Tag, Value> = WithProvider<UseFieldRef<Tag, Value>>;

The WithProvider adapter forwards a getter's provider-trait method to the inner provider's foundational method, and UseFieldRef<Tag, Value> is the foundational FieldGetter that reads the field at Tag and borrows it through AsRef. The UseFieldRef mechanism, including its mutable form, is documented on the UseFieldRef page, and the generated WithProvider impl on the WithProvider page.

Common Mistakes​

WithFieldRef cannot serve a -> &str getter. Value must be sized, and a &str return already makes the getter macros expect a String field, so WithFieldRef<Symbol!("name"), str> fails twice over:

error[E0277]: the size for values of type `str` cannot be known at compilation time
...
error[E0271]: type mismatch resolving `<UseFieldRef<Symbol<4, Chars<'n', Chars<'a', Chars<'m', Chars<'e', Nil>>>>>, str> as FieldGetter<Person, NameGetterComponent>>::Value == String`

Wire a &str getter over a String field to the plain UseField, which borrows through AsRef::as_ref.

  • WithProvider — the adapter this alias specializes.
  • UseFieldRef — the foundational getter it wraps, where the AsRef mechanism is documented.
  • WithField — the sibling alias for a field read directly, without the AsRef step.
  • #[cgp_getter] — defines the getter component this is wired to.
  • FieldGetter and MutFieldGetter — the provider-side getters the inner provider 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.