getter 🔬

Applies to: struct fields function arguments method arguments

Generates a getter method for a member. The method is callable only after the value for the member is set using any of its setters.

🔬 Experimental

This attribute is available under the cargo feature experimental-getter. Breaking changes may occur between minor releases but not between patch releases.

The fate of this feature depends on your feedback in the tracking issue #225. Please, let us know if you have any ideas on improving this attribute, or if it's already good enough!

The getter for a required member returns &T by default (can be overridden).

Struct

use bon::Builder;

#[derive(Builder)]
struct Example {
    #[builder(getter)] 
    x: u32,
}

let builder = Example::builder().x(1);

let x: &u32 = builder.get_x(); 

assert_eq!(*x, 1);

Function

use bon::builder;

#[builder]
fn example(
    #[builder(getter)] 
    x: u32,
) {}

let builder = example().x(1);

let x: &u32 = builder.get_x(); 

assert_eq!(*x, 1);

Method

use bon::bon;

struct Example;

#[bon]
impl Example {
    #[builder]
    fn example(
        #[builder(getter)] 
        x: u32,
    ) {}
}

let builder = Example::example().x(1);

let x: &u32 = builder.get_x(); 

assert_eq!(*x, 1);

The getter for an optional member returns Option<&T> by default (can be overridden).

use bon::Builder;

#[derive(Builder)]
struct Example {
    #[builder(getter)] 
    x1: Option<u32>,

    // Getters for `default` members are the same
    // as for members of type `Option<T>`
    #[builder(getter, default = 99)]              
    x2: u32,
}

let builder = Example::builder().x1(1).x2(2);

let x1: Option<&u32> = builder.get_x1(); 
let x2: Option<&u32> = builder.get_x2(); 

assert_eq!(x1, Some(&1));
assert_eq!(x2, Some(&2));

TIP

The getter for the member with #[builder(default)] returns Option<&T> because the default value is never stored in the builder. It's calculated lazily in the finishing function.

Config

You can override the return type of the getter, its name, visibility, and docs.

#[builder(
    getter(
        // Return `T` via `Copy`
        copy,

        // Return `T` via `Clone`
        clone,

        // Return `&<T as Deref>::Target`.
        deref,

        // Return the type specified in parens.
        // A deref coercion is expected to be valid to the specified type.
        // Don't specify the leading `&` here.
        deref(T),

        name = custom_name,
        vis = "pub(crate)",
        doc {
            /// Custom docs
        }
    )
)]

Overriding the return type

Here is an example of different return type configurations and what they generate.

use bon::Builder;
use std::rc::Rc;

#[derive(Builder)]
struct Example {
    // Generates `get_x1(&self) -> u32`
    #[builder(getter(copy))]               
    x1: u32,

    // Generates `get_x2(&self) -> String`
    #[builder(getter(clone))]              
    x2: String,

    // Generates `get_x3(&self) -> &str`
    #[builder(getter(deref))]              
    x3: String,

    // Generates `get_x4(&self) -> &str`
    #[builder(getter(deref(str)))]         
    x4: Rc<String>,
}

name

The default name for getter is get_{member}.

vis

The visibility must be enclosed with quotes. Use "" or "pub(self)" for private visibility.

The default visibility is the same as the visibility of the builder_type, which in turn, defaults to the visibility of the underlying struct or fn.

doc

Simple documentation is generated by default. The syntax of this attribute expects a block with doc comments.

doc {
    /// Doc comments
}