Tracking issue for File::with_options stabilisation

[Timmmm]

Implemented in #65429, behind feature flag with_options.

[Kinrany]

Just a thought about an alternative API:

let f = File::with_options("file.txt", |o| o.read(true).create(true));

[LPeter1997]

From the name I'd associate it with a function that takes an OpenOptions parameter, just like Vec::with_capacity takes a capacity. Basically not a builder type. For consistency's sake, why not either add a File::with_options(options: &OpenOptions) or rename it to something like File::builder()?

[Timmmm]

LPeter1997, that was my original suggestion but people overwhelmingly preferred this API.

[TheRadioGuy]

I agree with @LPeter1997. I think it'd be better to rename it to something like File::options()

[Timmmm]

I guess File::options() makes more sense when you just look at that API but File::with_options() makes more sense in typical usage.

let options = File::options(); // Ok
let options = File::with_options();  // Weird

let file = File::with_options().read(true).create(true).open("foo.txt"); // Ok
let file = File::options().read(true).create(true).open("foo.txt"); // Bit weirder. Maybe it is better actually?

Not that this is a democracy, but let's have a poll: upvote one or more of the following options...

[Timmmm]

pub fn with_options() -> OpenOptions {
  OpenOptions::new()
}

let options = File::with_options();
let file = File::with_options().read(true).create(true).open("foo.txt");

[Timmmm]

pub fn options() -> OpenOptions {
  OpenOptions::new()
}

let options = File::options();
let file = File::options().read(true).create(true).open("foo.txt");

[Timmmm]

pub fn builder() -> OpenOptions {
  OpenOptions::new()
}

let options = File::builder();
let file = File::builder().read(true).create(true).open("foo.txt");

[Kinrany]

From the API discovery point of view it's not great to have the only actual verb be the last in chain.

From the point of view of making code nicer to read, it's not great that open is not in any way syntactically distinguished from the rest of the methods. The reader has to inspect the types to find out that all but the last one return the same OpenOptions type. (It doesn't help that other methods are verbs too, even though they refer to fields and would be nouns in most other builders.)

[tesuji]

A PR changing the name to File::builder is up: #76744.