std.time.epoch: clean-ups

- Use consistent date format in documentation comments.
- Deprecate `epoch_year`: if anything it should be called `year`
  (though that's difficult due to aliasing) but I couldn't find anyone
  using this constant and I don't see how it would be useful unless you
  want to do time calculation on your own, but you can instead
  just use the functions provided by the structure.
- Deprecate `secs_per_day`: this already exists in `std.time`.
- Remove all `@as` in the file. All were unnecessary.
- Fix bad naming of structure names and fields.
  `YearAndDay` sounds like it's the year of the time and the day of the
  time, when actually it is the year o the time and the number of the
  days into the day, so that should definitely be plural.
- Fix redundant words in names. The entire file concerns itself with the
  Unix epoch so no need to repeat that.

Author: wooster0

lib/std/time/epoch.zig

@@ -1,28 +1,29 @@
-//! Epoch reference times in terms of their difference from
-//! UTC 1970-01-01 in seconds.
+//! Epoch reference times in terms of their difference from UTC 1970-01-01 in seconds.
+
 const std = @import("../std.zig");
+const time = std.time;
 const testing = std.testing;
 const math = std.math;
 
-/// Jan 01, 1970 AD
+/// 1970-01-01.
 pub const posix = 0;
-/// Jan 01, 1980 AD
+/// 1980-01-01.
 pub const dos = 315532800;
-/// Jan 01, 2001 AD
+/// 2001-01-01.
 pub const ios = 978307200;
-/// Nov 17, 1858 AD
+/// 1858-11-17.
 pub const openvms = -3506716800;
-/// Jan 01, 1900 AD
+/// 1900-01-01.
 pub const zos = -2208988800;
-/// Jan 01, 1601 AD
+/// 1601-01-01.
 pub const windows = -11644473600;
-/// Jan 01, 1978 AD
+/// 1978-01-01.
 pub const amiga = 252460800;
-/// Dec 31, 1967 AD
+/// 1967-12-31.
 pub const pickos = -63244800;
-/// Jan 06, 1980 AD
+/// 1980-01-06.
 pub const gps = 315964800;
-/// Jan 01, 0001 AD
+/// 0001-01-01.
 pub const clr = -62135769600;
 
 pub const unix = posix;
@@ -39,10 +40,13 @@ pub const brew = gps;
 pub const atsc = gps;
 pub const go = clr;
 
-/// The type that holds the current year, i.e. 2016
+/// Example: 2016.
 pub const Year = u16;
 
+/// Deprecated: use functions provided by this structure.
 pub const epoch_year = 1970;
+
+/// Deprecated: use `std.time.s_per_day`.
 pub const secs_per_day: u17 = 24 * 60 * 60;
 
 pub fn isLeapYear(year: Year) bool {
@@ -78,21 +82,20 @@ pub const Month = enum(u4) {
     nov,
     dec,
 
-    /// return the numeric calendar value for the given month
-    /// i.e. jan=1, feb=2, etc
-    pub fn numeric(self: Month) u4 {
-        return @intFromEnum(self);
+    /// Returns the numeric calendar value for the given month, i.e. jan=1, feb=2, etc.
+    pub fn numeric(month: Month) u4 {
+        return @intFromEnum(month);
     }
 };
 
-/// Get the number of days in the given month and year
+/// Returns the number of days in the given year and month.
 pub fn getDaysInMonth(year: Year, month: Month) u5 {
     return switch (month) {
         .jan => 31,
-        .feb => @as(u5, switch (isLeapYear(year)) {
+        .feb => switch (isLeapYear(year)) {
             true => 29,
             false => 28,
-        }),
+        },
         .mar => 31,
         .apr => 30,
         .may => 31,
@@ -106,118 +109,124 @@ pub fn getDaysInMonth(year: Year, month: Month) u5 {
     };
 }
 
-pub const YearAndDay = struct {
+/// The year of the time and the number of days into the year.
+pub const YearAndDays = struct {
     year: Year,
-    /// The number of days into the year (0 to 365)
-    day: u9,
+    /// The number of days into the year (0 to 365).
+    days: u9,
 
-    pub fn calculateMonthDay(self: YearAndDay) MonthAndDay {
+    pub fn calculateMonthAndDay(year_and_days: YearAndDays) MonthAndDay {
         var month: Month = .jan;
-        var days_left = self.day;
+        var days_left = year_and_days.days;
         while (true) {
-            const days_in_month = getDaysInMonth(self.year, month);
+            const days_in_month = getDaysInMonth(year_and_days.year, month);
             if (days_left < days_in_month)
                 break;
             days_left -= days_in_month;
-            month = @as(Month, @enumFromInt(@intFromEnum(month) + 1));
+            month = @enumFromInt(@intFromEnum(month) + 1);
         }
-        return .{ .month = month, .day_index = @as(u5, @intCast(days_left)) };
+        return .{ .month = month, .day_index = @intCast(days_left) };
     }
 };
 
+/// The month and day of the time.
 pub const MonthAndDay = struct {
     month: Month,
-    day_index: u5, // days into the month (0 to 30)
+    /// The day of the month (0 to 30).
+    day_index: u5,
 };
 
-/// days since epoch Jan 1, 1970
-pub const EpochDay = struct {
-    day: u47, // u47 = u64 - u17 (because day = sec(u64) / secs_per_day(u17)
-    pub fn calculateYearDay(self: EpochDay) YearAndDay {
-        var year_day = self.day;
-        var year: Year = epoch_year;
+/// Days since the epoch.
+pub const Days = struct {
+    days: u47, // = u64 - u17 (because day = sec(u64) / time.s_per_day(u17)
+
+    pub fn calculateYearAndDays(days: Days) YearAndDays {
+        var year_days = days.days;
+        var year: Year = 1970;
         while (true) {
             const year_size = getDaysInYear(year);
-            if (year_day < year_size)
+            if (year_days < year_size)
                 break;
-            year_day -= year_size;
+            year_days -= year_size;
             year += 1;
         }
-        return .{ .year = year, .day = @as(u9, @intCast(year_day)) };
+        return .{ .year = year, .days = @intCast(year_days) };
     }
 };
 
-/// seconds since start of day
+/// Seconds into the day.
 pub const DaySeconds = struct {
-    secs: u17, // max is 24*60*60 = 86400
+    secs: u17, // Maximum is `time.s_per_day`.
 
-    /// the number of hours past the start of the day (0 to 23)
-    pub fn getHoursIntoDay(self: DaySeconds) u5 {
-        return @as(u5, @intCast(@divTrunc(self.secs, 3600)));
+    /// Returns the number of hours past the start of the day (0 to 23).
+    pub fn getHoursIntoDay(day_seconds: DaySeconds) u5 {
+        return @intCast(@divTrunc(day_seconds.secs, 3600));
     }
-    /// the number of minutes past the hour (0 to 59)
-    pub fn getMinutesIntoHour(self: DaySeconds) u6 {
-        return @as(u6, @intCast(@divTrunc(@mod(self.secs, 3600), 60)));
+
+    /// Returns the number of minutes past the hour (0 to 59).
+    pub fn getMinutesIntoHour(day_seconds: DaySeconds) u6 {
+        return @intCast(@divTrunc(@mod(day_seconds.secs, 3600), 60));
     }
-    /// the number of seconds past the start of the minute (0 to 59)
-    pub fn getSecondsIntoMinute(self: DaySeconds) u6 {
-        return math.comptimeMod(self.secs, 60);
+
+    /// Returns the number of seconds past the start of the minute (0 to 59).
+    pub fn getSecondsIntoMinute(day_seconds: DaySeconds) u6 {
+        return math.comptimeMod(day_seconds.secs, 60);
     }
 };
 
-/// seconds since epoch Jan 1, 1970 at 12:00 AM
-pub const EpochSeconds = struct {
+/// Seconds since the epoch.
+pub const Seconds = struct {
     secs: u64,
 
-    /// Returns the number of days since the epoch as an EpochDay.
-    /// Use EpochDay to get information about the day of this time.
-    pub fn getEpochDay(self: EpochSeconds) EpochDay {
-        return EpochDay{ .day = @as(u47, @intCast(@divTrunc(self.secs, secs_per_day))) };
+    /// Returns the number of days since the epoch as an Days.
+    /// Use Days to get information about the day of this time.
+    pub fn getDays(seconds: Seconds) Days {
+        return Days{ .days = @intCast(@divTrunc(seconds.secs, time.s_per_day)) };
     }
 
     /// Returns the number of seconds into the day as DaySeconds.
     /// Use DaySeconds to get information about the time.
-    pub fn getDaySeconds(self: EpochSeconds) DaySeconds {
-        return DaySeconds{ .secs = math.comptimeMod(self.secs, secs_per_day) };
+    pub fn getSecondsIntoDay(seconds: Seconds) DaySeconds {
+        return DaySeconds{ .secs = math.comptimeMod(seconds.secs, time.s_per_day) };
     }
 };
 
-fn testEpoch(secs: u64, expected_year_day: YearAndDay, expected_month_day: MonthAndDay, expected_day_seconds: struct {
-    /// 0 to 23
+fn testDecode(secs: u64, expected_year_day: YearAndDays, expected_month_day: MonthAndDay, expected_day_seconds: struct {
+    /// 0 to 23.
     hours_into_day: u5,
-    /// 0 to 59
+    /// 0 to 59.
     minutes_into_hour: u6,
-    /// 0 to 59
+    /// 0 to 59.
     seconds_into_minute: u6,
 }) !void {
-    const epoch_seconds = EpochSeconds{ .secs = secs };
-    const epoch_day = epoch_seconds.getEpochDay();
-    const day_seconds = epoch_seconds.getDaySeconds();
-    const year_day = epoch_day.calculateYearDay();
-    try testing.expectEqual(expected_year_day, year_day);
-    try testing.expectEqual(expected_month_day, year_day.calculateMonthDay());
+    const seconds = Seconds{ .secs = secs };
+    const days = seconds.getDays();
+    const day_seconds = seconds.getSecondsIntoDay();
+    const year_and_days = days.calculateYearAndDays();
+    try testing.expectEqual(expected_year_day, year_and_days);
+    try testing.expectEqual(expected_month_day, year_and_days.calculateMonthAndDay());
     try testing.expectEqual(expected_day_seconds.hours_into_day, day_seconds.getHoursIntoDay());
     try testing.expectEqual(expected_day_seconds.minutes_into_hour, day_seconds.getMinutesIntoHour());
     try testing.expectEqual(expected_day_seconds.seconds_into_minute, day_seconds.getSecondsIntoMinute());
 }
 
-test "epoch decoding" {
-    try testEpoch(0, .{ .year = 1970, .day = 0 }, .{
+test "decoding" {
+    try testDecode(0, .{ .year = 1970, .days = 0 }, .{
         .month = .jan,
         .day_index = 0,
     }, .{ .hours_into_day = 0, .minutes_into_hour = 0, .seconds_into_minute = 0 });
 
-    try testEpoch(31535999, .{ .year = 1970, .day = 364 }, .{
+    try testDecode(31535999, .{ .year = 1970, .days = 364 }, .{
         .month = .dec,
         .day_index = 30,
     }, .{ .hours_into_day = 23, .minutes_into_hour = 59, .seconds_into_minute = 59 });
 
-    try testEpoch(1622924906, .{ .year = 2021, .day = 31 + 28 + 31 + 30 + 31 + 4 }, .{
+    try testDecode(1622924906, .{ .year = 2021, .days = 31 + 28 + 31 + 30 + 31 + 4 }, .{
         .month = .jun,
         .day_index = 4,
     }, .{ .hours_into_day = 20, .minutes_into_hour = 28, .seconds_into_minute = 26 });
 
-    try testEpoch(1625159473, .{ .year = 2021, .day = 31 + 28 + 31 + 30 + 31 + 30 }, .{
+    try testDecode(1625159473, .{ .year = 2021, .days = 31 + 28 + 31 + 30 + 31 + 30 }, .{
         .month = .jul,
         .day_index = 0,
     }, .{ .hours_into_day = 17, .minutes_into_hour = 11, .seconds_into_minute = 13 });