Proposal: DateTime in std.time

[tau-dev]

It could be very useful to have something like:

// Strictly Gregorian
const DateTime = struct {
    sec: u6, // [0, 60]
    min: u6, // [0, 59]
    hour: u5, // [0, 23] 
    year_day: u9, // [1, 366]
    year: i16, // C.E.

    pub fn monthDay(date: Self) u5; // [1, 31]
    pub fn month(date: Self) u4; // [1, 12]
    pub fn weekDay(date: Self) u8; // [0, 6]
    pub fn week(date: Self) u6; // [1, 54]
    pub fn isLeapYear(date: Self) bool;

    /// utc_offset is in minutes.
    pub fn fromEpoch(epoch: i64, utc_offset: i16) Self;
    pub fn toEpoch(date: Self, utc_offset: i16) i64;
};

// Posix Epoch repeats on leap seconds, International Atomic Time is useful for strictly monotonic time stamps.
// As far as I understood https://techcommunity.microsoft.com/t5/networking-blog/leap-seconds-for-the-appdev-what-you-should-know/ba-p/339813, 
// it seems like Windows' GetSystemTimeAsFileTime follows IAC.
pub fn epochToAtomicTime(epoch: i64, leap_seconds: []const i64) i64;
pub fn atomicTimeToEpoch(atomic: i64, leap_seconds: []const i64) i64;

Maybe also with a more elegant way to format it than passing the fields seperately to fmt.format.

[ikskuh]

I think having a proper well-made date/time library is important, but it's not a good idea to include this in std. A recommended date/time library would be better.

But yes, i agree that having a date-time api would be a good idea!

[tau-dev]

This proposal is fairly similar to C's tm from time.h. Are there any guidelines as to what should be in zig's std library?

[Mouvedia]

    sec: u8, // [0, 60]
    min: u8, // [0, 59]
    hour: u8, // [0, 23] 
    year_day: u16, // [0, 365]

should be

    sec: u6, // [0, 60]
    min: u6, // [0, 59]
    hour: u5, // [0, 23]
    day: u5, // [1, 31]
    month: u4, // [1, 12]
    year_day: u9, // [1, 366]

[ikskuh]

@Mouvedia

sec: u6, // [1, 59] is horribly wrong. This ignores leap seconds, also you cannot have 8:00 in the morning with this ;)

I plead everyone here to read Falsehoods programmers believe about time as it lists a whole bunch of misconceptions about date/time values

[RogierBrussee]

Seconds are far, far too little resolution when atomic clocks are used as a reference (e.g. in GPS).

In glibc struct timespec allows to specify nanosecond, and was the result of a long painful learning experience.
Why not just add convenience accessor functions to specify days and months, hours, minutes and seconds, to a structure that is binary compatible with struct timespec?

[tau-dev]

@RogierBrussee DateTime would be used for human-readable displaying, is there any use-case for nanoseconds there?
How would you modify the proposal?

Why not just add convenience accessor functions to specify days and months, hours, minutes and seconds [...]?

That is exactly what this is.

... binary compatible with struct timespec

timespec is not cross-platform, the standard library functions return i64 second or i128nanosecond timestamps.

@Mouvedia You're probably right. Modified the proposal.

[laserbeam3]

I think having a proper well-made date/time library is important, but it's not a good idea to include this in std. A recommended date/time library would be better.

There's a risk of becoming like python's datetime with this approach. Theres a datetime lib in std which does most of what you want, but doesn't actually work, and a 3rd party recommended lib which actually works, but is not fully compatible with the standard one. Whatever happens, half of a datetime lib in std is a bit painful :(

[RogierBrussee]

@InterplanetaryEngineer
If the clock in your computer runs at 3.3 GHZ then it has 1/3ns resolution, but admittedly that is not absolute time. The javascript DOMHighresolutionTimestamp() is in microseconds. Miliseconds, that's what the Olympic 100m is decided on. Mere seconds are just too low a resolution for many events, so it is better to have plenty of room below.

Your datamodel makes it impossible to have higher than 1 second resolution however. For the interface, it should not matter what the datamodel is as long as it allows sufficient resolution: struct timespec is effectively a i128 worth of nanoseconds. I don't really see why it is not cross platform (glibc is). Windows just does not use it in its native interfaces.

[Mouvedia]

The javascript DOMHighresolutionTimestamp() is in microseconds

It depends.
Safari and Firefox have set their resolution to 1ms, others vary between 5µs and 100µs.

[matu3ba]

@RogierBrussee see here. POSIX does not specify, if time_t is signed or unsigned. Some history.

Being signed would have the advantage to represent events before midnight UTC of January 1, 1970. DateTime should offer some common operations for DateTime comparison, so the potential negative signedness would not be of significance as potential error source.

Otherwise an unsigned representation would be better to prevent errors.