jiff

As originally brought up in #390, my personal belief is that the plural/singular nature of method names should match how would one refer to the quantity of the referenced parameter (or result) in speech. As a concrete example, I found (and continue to find) the naming of and to be confusing as I am passing/receiving multiple milliseconds as the input/result from these functions, especially when much of the rest of the library methods use plural naming conventions (not to mention that for me personally it conflicts with my established muscle memory from numerous other date/time libraries that use and ). @\BurntSushi was kind enough to explain the original intention behind the singular naming: the idea is to reflect that this is in reference to a singular, unique moment in time while the plural names reflect generic amounts of time that don't map out as cleanly (or round-trip equivalently between the corresponding types?). While that explained the rationale behind the singular names and indeed provides some extra layer of semantic clarity when using the library, I think there might be merit in using consistent singular/plural naming throughout the library (not to mention that while the result might be a singular moment in time, it is still nevertheless composed of multiple milliseconds (or whatever units) and referring to these compositional units in the singular is probably still going to trip up users). Personally, I think the presence of the and prefixes is itself (enough of) a good means of conveying that these parameters/return values map out to the same/equivalent unit of time without relying on the singular/plural name as an additional signal. This means even if/when you rename both and, e.g., to plural, it's still enough to indicate (whether on its own or compared to another function) whether it is returning a value equivalent to the entire amount or a compositional/partial value.

I think it's useful to provide a primitive that can represent a date as a count of the number of days since . Column oriented data processing really likes having a 32-bit integer for this. _And_ certain calculations (like finding the weekday) really want to start with a Unix epoch day. e.g., first converts from the Gregorian date to a Unix epoch day internally, and then does a little math to compute the actual weekday. Exposing a type would permit calls to amortize this operation at their convenience. Ref https://github.com/apache/datafusion-comet/issues/4754

Specifically, this table: https://docs.rs/jiff/latest/jiff/fmt/index.html#support-for-fromstr-and-display I think we should just add a note that there is substantial overlap between specifications. RFC 3339, RFC 9557 and ISO 8601 in particular. We might want to say that when there is overlap, the table lists the more _precise_ specification. It's more complicated than that, especially when it comes to things described by ISO 8601, since ISO 8601 contains things that aren't in RFC 3339 or RFC 9557. And Jiff doesn't support all of ISO 8601. In contrast, RFC 3339 is generally a strict subset of RFC 9557.