| In my head, a Date.t is semantically a duration. So it’s completely valid to pass it as a duration to Date.shift as I see it. Which argues for singular names.
This conversation is a bit like “is a date a point in time or an interval”. And the answer is yes, depending. Sent from my iPhone On 8 Mar 2024, at 14:39, Sabiwara Yukichi <sabiw...@gmail.com> wrote:
I'm personally leaning more towards the plural, because it feels semantically more correct to treat a point of time and a duration as separate.
d.year means the same thing if d is either a date or a datetime, but for a duration calling it d.years emphasizes the difference.
It could perhaps help catch errors as well, both for the human and the compiler. One (arguably contrived) example would be structurally typed code which doesn't enforce any type in particular but uses the dot access or partial pattern matches like %{year: ..., month: ...} in order to support both dates or datetimes. Passing in a duration wouldn't make sense semantically, having different names would make it fail properly.
I also agree with other reasons mentioned, the known standard one especially.
Right, it would make using a Duration in combination with the `add/2-3` functions much harder than it needs to be. So far all time units in Elixir are singular, and I think we do gain something from consistently sticking to that, regardless of the context of durations, calendar types and what not.
I've seen some libraries allowing both, singular and plural, which i dont want to have anything to do with, except for mentioning it though haha.
What i currently see is:
Reasons for plural: - Known standard across various libraries and programming languages - Sounds natural, to shift a date by "3 months" instead of "3 month".
Reasons for singular: - Compatible with time units already defined in Elixir (also relevant for extending the use of Duration later on) - Reduced cognitive load as the time units are always spelled the same regardless of the context
The reasons for singular do outweigh the reasons for plural, so unless we're making some very strong points for diverging from that, let's keep it singular!
On Thursday, March 7, 2024 at 7:39:15 AM UTC+1 José Valim wrote:
Compatibility with the other time units is an important point. My mind is back on singular again. :) While i was strongly leaning towards singular, i understand why one would expect plural. Given that seems to be pretty standard in wild, i am fine changing it as well.
What mostly put me off about was that we'd end up with `Time.add(t, 3, :minute)` vs `Time.shift(t, minutes: 3)`, which after all, maybe isn't too bad, as we can keep the plural keys exclusive to durations. Another reason for going with plurals is that it _should_ make migrating from some libraries to the standard library relatively straight forward (with the exception of microseconds).
On Wednesday, March 6, 2024 at 11:07:52 PM UTC+1 José Valim wrote:
After a quick glance on other programming languages, it seems Python, Java, Rust, and C# all have plural names. Erlang also uses plural in its helper functions in the timer module. So we might want to follow suit. We discussed plural vs singular and settled on singular so it mirrors the calendar types. Thoughts? +1 for this, awesome work Theo. Shifting dates/timestamps is such a common operation and a standard implementation would be beneficial for everybody.
PS. I would expect plural in the duration fields.
The main argument for having it in core is: * It integrates directly with the Calendar behaviour * We could provide built-in sigils in the future to create readable durations, such as ~P[3 hours and 10 minutes] * Postgrex, Explorer, CLDR, etc all implement their own version of durations Arguments for not having it in core: it happens that all of the arguments above can also be solved without adding Duration to Elixir and, instead, by creating a custom library: * A separate library could extend the calendar behaviour with shift_* functions * Third-party sigils can also be provided by libraries * Postgrex, Explorer, and CLDR could create or use a package with a duratio type shared across them all
I would love to hear the community thoughts.
Preface
We currently have `add/2-3` to manipulate calendar types in the standard library. These functions allow adding a specified amount of time of given unit to a date/time. The standard library currently misses means to apply more complex, or logical durations to calendar types. e.g. adding a month, a week, or one month and 10 days to a date.
Reasons for it
While similar functionality exists in libraries, such as CLDR, Timex, Tox, adding this functionality to the standard library has already been requested and discussed at multiple occasions over the past years. To list a few examples:
Furthermore the shift behaviour in the extremely popular library Timex changed in Elixir >= 1.14.3 which may have complicated the mostly lean and non-breaking language upgrade Elixir has to offer.
Elixir has a great set of modules and functions that deal with date and time, the APIs are consistent and `shift/2-3` should fit right in, solving many standard needs of various industries, be it for reporting, appointments, events, finance... the list goes on, engineers probably face the need to shift time logically more often than not in their careers.
Technical details
Duration A date or time must be shifted by a duration. There is an ISO8601 for durations, which the initial implementation is loosely following. The structure of a Duration lives in its own module with its own set of functions to create and manipulate durations. One example of where it diverts from the ISO standard, is that it implements microseconds. Microseconds in a duration are stored in the same format as in the time calendar types, meaning they integrate well and provide consistency.
Shift The shift behaviour is implemented as a callback on Calendar and supported by all calendar types: Date, DateTime, NaiveDateTime and Time. Date, Time and NaiveDateTime each have their own implementation of a "shift", while DateTime gets converted to a NaiveDateTime before applying the shift, and is then rebuilt to a DateTime in its original timezone. `shift/2-3` also has guaranteed output types (which isn't a given in many libraries) and follows the consistent API which is established in the calendar modules.
Benchmarks
There are some benchmarks + StreamData tests in the PR description.
Outlook
After adding the Duration type and shift behaviour to the standard library, the following things could be explored and derived from the initial work:
- Implementing a protocol that allows Duration to be applied to any data type, not just dates and times.
- A range-like data type that allows us to do recurring constructs on any data type. For example, Duration.interval(~D[2000-01-01], month: 1), when iterated, would emit {:ok, date} | {:error, start, duration, reason} entries
- A sigil for easy creation of durations: ~P[3 hours and 10 minutes]
- Making it so add/2-3 reuses the shift_* functions
Reasons against it
While I am convinced that adding `shift/2-3` to the standard library would be very beneficial, nothing really speaks against the points mentioned above to be implemented in a library instead. However, something as crucial and central as date/time manipulation should still be part of the standard library, negating the risk of breaking changes, inconsistent behaviour and outdated or too unique ergonomics which aren't widely applicable, unlike what should be part of the standard library.
Many thanks to @jose & @kip for the initial reviews and everyone in advance taking the time to read the proposal!
Looking forward to hear other peoples ideas and opinions on the subject!
--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscr...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/786f6323-7f47-44dc-8438-8a6fc94737afn%40googlegroups.com.
--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscr...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CANnyohYGR832XTg9SawCtat3NKxJVMu%3D7KW%3D8VJ7fTCjQro8Eg%40mail.gmail.com.
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscr...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/5C8C67FE-2A5D-4375-B316-B49727955084%40gmail.com.
|
