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 <jose.va...@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 > <mailto: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.va...@dashbit.co >> <mailto:jose.va...@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-lang-core@googlegroups.com >>> <mailto: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 <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-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/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-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/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-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/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-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/CAGnRm4%2BNWO687y8hOWhGFLLAWWF_bwJ8bJ1%3Dd%3DPOWgH9a%3DfdYQ%40mail.gmail.com > > <https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2BNWO687y8hOWhGFLLAWWF_bwJ8bJ1%3Dd%3DPOWgH9a%3DfdYQ%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-core+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/36B8F628-73AB-44FC-A1BD-714ED8008B18%40gmail.com.
