> 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.
I very very nearly did this in ex_cldr_calendars but I’m glad I didn’t. I think it looks good on the surface but creates lots of confusion and ambiguity late. > On 7 Mar 2024, at 6:07 pm, 'Theo Fiedler' via elixir-lang-core > <elixir-lang-core@googlegroups.com> wrote: > > 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. :) >> >> On Thu, Mar 7, 2024 at 07:20 'Theo Fiedler' via elixir-lang-core >> <elixir-l...@googlegroups.com <>> wrote: >>> 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. >>>> >>>> On Wed, Mar 6, 2024 at 23:03 José Valim <jose....@dashbit.co <>> wrote: >>>>> We discussed plural vs singular and settled on singular so it mirrors the >>>>> calendar types. Thoughts? >>>>> >>>>> On Wed, Mar 6, 2024 at 23:01 Panagiotis Nezis <pne...@gmail.com <>> wrote: >>>>>> +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. >>>>>> >>> >>>>>> On Wed, Mar 6, 2024 at 8:23 PM José Valim <jose....@dashbit.co <>> wrote: >>> >>> >>>>>>> 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. >>>>>>> >>> >>> >>>>>>> On Wed, Mar 6, 2024 at 7:16 PM 'Theo Fiedler' via elixir-lang-core >>>>>>> <elixir-l...@googlegroups.com <>> wrote: >>> >>> >>>>>>>> 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: >>>>>>>> >>>>>>>> - https://github.com/elixir-lang/elixir/pull/10199 >>>>>>>> - https://elixirforum.com/t/get-date-n-months-years-in-the-past/48346/3 >>>>>>>> - >>>>>>>> https://elixir-lang.slack.com/archives/C0HEX82NR/p1709581478427009?thread_ts=1709368588.334759&cid=C0HEX82NR >>>>>>>> >>>>>>>> Furthermore the shift behaviour in the extremely popular library Timex >>>>>>>> changed <https://github.com/bitwalker/timex/issues/731> 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 <https://en.wikipedia.org/wiki/ISO_8601#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. >>>>>>>> >>>>>>>> Find the current state of the implementation here: >>>>>>>> https://github.com/elixir-lang/elixir/pull/13385 >>>>>>>> >>>>>>>> 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. >>> >>>>>>>> To unsubscribe from this group and stop receiving emails from it, send >>>>>>>> an email to elixir-lang-co...@googlegroups.com <>. >>>>>>>> To view this discussion on the web visit >>>>>>>> https://groups.google.com/d/msgid/elixir-lang-core/cb0ed628-3848-4de0-aa13-c0f4761e4d99n%40googlegroups.com >>>>>>>> >>>>>>>> <https://groups.google.com/d/msgid/elixir-lang-core/cb0ed628-3848-4de0-aa13-c0f4761e4d99n%40googlegroups.com?utm_medium=email&utm_source=footer>. >>>>>> >>>>>>>> >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> 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 <>. >>>>>>> To view this discussion on the web visit >>>>>>> https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2BNmFsMhbkRubMjnmM8c_Amq8DgmKCJtzJ1GEuM4-sVgw%40mail.gmail.com >>>>>>> >>>>>>> <https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2BNmFsMhbkRubMjnmM8c_Amq8DgmKCJtzJ1GEuM4-sVgw%40mail.gmail.com?utm_medium=email&utm_source=footer>. >>>>>> >>>>>> >>>>>> -- >>>>>> 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 <>. >>>>>> To view this discussion on the web visit >>>>>> https://groups.google.com/d/msgid/elixir-lang-core/CAPxxbtjvFwnMXe134RR8wjnYk%2Bm-%2BF%2BO_79dWKk3G-bt99Ln%2Bw%40mail.gmail.com >>>>>> >>>>>> <https://groups.google.com/d/msgid/elixir-lang-core/CAPxxbtjvFwnMXe134RR8wjnYk%2Bm-%2BF%2BO_79dWKk3G-bt99Ln%2Bw%40mail.gmail.com?utm_medium=email&utm_source=footer>. >>> >>> >>> -- >>> 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 <>. >> >>> To view this discussion on the web visit >>> https://groups.google.com/d/msgid/elixir-lang-core/3a82f501-cc62-409c-a653-d4b6e5943407n%40googlegroups.com >>> >>> <https://groups.google.com/d/msgid/elixir-lang-core/3a82f501-cc62-409c-a653-d4b6e5943407n%40googlegroups.com?utm_medium=email&utm_source=footer>. > > > -- > 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 > <mailto: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 > > <https://groups.google.com/d/msgid/elixir-lang-core/786f6323-7f47-44dc-8438-8a6fc94737afn%40googlegroups.com?utm_medium=email&utm_source=footer>. -- 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/437596E2-7D1D-41C9-89EF-792F08FCF965%40gmail.com.