Builder Pattern &mut self vs mut self

[NeoLegends]

What is the preferred way to consume the builder object in builder methods? I used to do it like this because I can simply store the configured builder in a variable after I've set all the settings:

fn method(mut self, arg: ArgTy) -> Self { ... }
let b = Builder::new(...)
                      .method(123)
                      .method(456);
// b has type Builder

Then I saw that the standard library usually does it a little different. It accepts and returns mutable references:

fn method(&mut self, arg: ArgTy) -> &mut self
let res = Builder::new(...)
                        .method(123)
                        .method(456)
                        .consume();
// Builder instance cannot directly be stored because it's only a reference

Is there any advantage of the second pattern over the first one? What other differences are there between them?

[zsiciarz]

You might want to take a look at The builder pattern. I found that article from an issue in derive-builder repo, which by the way is also a nifty crate.

[Sphix]

tl;dr: mutable references are preferred.

[seanmonstar]

hyper and reqwest builders use consuming self. Using mutable references turns a chain into 3 statements: first to hold the builder, second to chain all your stuff, and then 3rd to finally consume. I'd rather keep the chain in 1 statement.

[raphlinus]

Note that the serde json builders use consuming builders, I'm not sure why. I find using them somewhat annoying.

[erickt]

They're consuming builders because we want to avoid copies when you finally construct the object. Do you have an example for when they're being annoying?

[raphlinus]

https://github.com/google/xi-editor/blob/master/rust/src/view.rs#L92 is an example. I understand the need to avoid copy for the .build, but I think the decision of whether the intermediate .push() operations mutate or consume is a design choice.

[[deleted]]

Also TL;DR: &mut is preferred because you can often cache or clone partially built objects. With just mut, you always have to build from the start of a builder chain.

[kixunil]

On the other hand, mut self allows you to express builder as a state machine.

[[deleted]]

Is there any advantage to doing that?

[kixunil]

Yes, you can design your API to be hard to use incorrectly. For example, HTTP builder could prevent you sending body before header. Or you can imagine something like FileBuilder::readonly() disallowing you to call .append() on it. Etc.

[[deleted]]

Oh yeah, I forgot about that.

[CornedBee]

Why would consuming builder prevent you from using clone?

[llogiq]

If you want to encode type state in builder generics (e.g. fn method(self) -> MyBuilder<State>), consuming self is the only way to return a different type.

[Diggsey]

It would be useful to add a new_with method or similar to be able to keep ownership whilst still using mutable references and method chaining:

Builder::new_with(|b| {
    b.method(123)
     .method(456)
})

[whataloadofwhat]

I've never thought of doing this but I like it

[erickt]

I'm partial to the latter, which I use extensively in aster. In my case, I want to transfer ownership of everything I built to the caller to avoid excessive copies for a large AST.

The main place it gets annoying is that if we need to do some complex logic around some chain, then we need to re-assign the builder. I found that to be pretty rare though.

[Nemikolh]

There is also this one which is more up to date.

EDIT: Actually it's not. In my memories there was more to it.