Re: [elixir-core:11685] [Proposal] Add `shift/2-3` to calendar types

[Kip Cole]

> 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 
>  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 
>> > 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 > 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 > 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 > 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 
>>> > 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:
 

Re: [elixir-core:11685] [Proposal] Add `shift/2-3` to calendar types

['Theo Fiedler' via elixir-lang-core]

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  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  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  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  in 
>>>

Re: [elixir-core:11683] [Proposal] Add `shift/2-3` to calendar types

[José Valim]

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-lang-core@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  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  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  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  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

Re: [elixir-core:11683] [Proposal] Add `shift/2-3` to calendar types

['Theo Fiedler' via elixir-lang-core]

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  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  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  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  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 
> th

Re: [elixir-core:11681] [Proposal] Add `shift/2-3` to calendar types

[José Valim]

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  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  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  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-lang-core@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  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.

 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.

Re: [elixir-core:11680] [Proposal] Add `shift/2-3` to calendar types

[Kip Cole]

I went with plurals in my ex_cldr_calendars implementation and I wish I didn’t. 
 Consistency across APIs reduces cognitive load in my opinion, even if 
grammatically (in English) dissonant.

> On 7 Mar 2024, at 9:03 am, José Valim  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  > 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 > > 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 
>>> >> > 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  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.
 
 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

Re: [elixir-core:11679] [Proposal] Add `shift/2-3` to calendar types

[José Valim]

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  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  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-lang-core@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  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.
>>>
>>> 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_* 

Re: [elixir-core:11678] [Proposal] Add `shift/2-3` to calendar types

[Panagiotis Nezis]

+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  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-lang-core@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  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.
>>
>> 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 

Re: [elixir-core:11677] [Proposal] Add `shift/2-3` to calendar types

[José Valim]

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-lang-core@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  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.
>
> 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 ti

[elixir-core:11677] [Proposal] Add `shift/2-3` to calendar types

['Theo Fiedler' via elixir-lang-core]

*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  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.

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-core+unsubscr...@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.