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.

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>.

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 additionally override the name, visibility and docs for the getter method.

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

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
}