Why are Span methods like hours() or minutes() setters instead of getters?

[epidemian]

I'll preface this by saying that i'm quite a noob at Rust, so this might be a very stupid question. But, i found it weird when reading Jiff's docs that methods like Span::hours() mutate the span instead of returning the value of that field. For doing the latter, there are methods like Span::get_hours() that act like getters.

This goes a bit contrary to what i thought was Rust's convention for getters/setters. I would've expected Span::hours() & Span::set_hours() as getter & setter respectively.

Why where these methods named this way?

This document for API Guidelines confirmed this getter convention, but it says nothing about setters:

With a few exceptions, the get_ prefix is not used for getters in Rust code.

---

Some speculation / ideas...

The only reason i can think of for having methods hours() as setters is because Spancomes with a sort of built-in builder pattern, to make them easier to construct. An example taken from the docs:

use jiff::ToSpan;

let span = 5.days().hours(8).minutes(1);

Is this the reason for this design decision?

If so, then i find it a bit unfortunate to end up with these not-very-conventional getters like get_hours() as the price for having more concise building.

If the idea is to use the extension methods on numbers as a more concise way of building Spans, then why not go all-in on these?

use jiff::ToSpan;

let span = 5.days() + 8.hours() + 1.minutes();

And then we could have more conventional getters, like .hours(), and also simpler setters, like a .set_hours() that doesn't need to be self-returning (or .with_hours() if the builder pattern is preferred).

WDYT?

[BurntSushi]

I answered what I believe is a related question in a more focused way in #41. The answer to that somewhat subsumes this question because it effectively rejects your suggestion of using operator overloading on addition to make constructing spans easier.

With that said, it is technically separable from the problem of using the get_ prefix in getters.

I use the pattern of the get_ prefix for getters in regex-automata as well: https://docs.rs/regex-automata/latest/regex_automata/meta/struct.Config.html

The main reason for this is that I perceive the getters in this case to be less frequently used---by a substantial amount---than the builder/setters. The Rust API guidelines are just that; guidelines. They aren't rules we must follow, and when the benefits of following them get dwarfed by the costs or the benefits of an alternative approach, then I firmly believe in feeling free to move away from the guideline. That's what I did here. I did not choose to use a get_ prefix because I like prefixing getters that way. I chose that because I wanted the setter-builders to be very concise and easy to use.

Given that, I believe, overloading + is off the table, I'm not sure I really see another alternative here.

Someone did float the idea of adding free functions to Jiff for constructing single-unit spans, and this would avoid the prefix-suffix flipping used by the current ToSpan trait. For example, jiff::years(3).months(5). But to do that, you still need to have setter-builders and getters with a get_ prefix.

Another choice is to have a separate Span builder type, but I think that's likely to be quite unergonomic.

[epidemian]

Thanks for the patience and thorough responses @BurntSushi!

They aren't rules we must follow, and when the benefits of following them get dwarfed by the costs or the benefits of an alternative approach, then I firmly believe in feeling free to move away from the guideline.

Yeah, that's totally reasonable i think. And i agree, it's fine to break conventions in such cases where they'd do more harm than good.

That being said, if the main (and maybe only) reason for having the shorter names like hours() be builder/setters instead of getters is to have a more convenient way of building span, then would you consider making them getters if a neater way of building spans without them is found? If so, i've added some brainstorming ideas on discussion #41 :)

[BurntSushi]

If we come up with a scheme where setter-builder methods aren't needed on Span, or are at least expected to be infrequently used, then yes, I wouldn't mind dropping the get_ prefix. But at this point, I am not particularly hopeful for such an approach. I also personally don't think there is much cost to the get_ prefix. Like, it doesn't really bother me and I don't think it's going to result in bugs.