Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/time/epoch.zig

Source line 1

Epoch reference times in terms of their difference from UTC 1970-01-01 in seconds.

std.time.epoch.amiga

constant

Source line 20

Jan 01, 1978 AD

std.time.epoch.android

alias

Source line 29

Alias of std.time.epoch.posix

std.time.epoch.aros

alias

Source line 36

Alias of std.time.epoch.amiga

std.time.epoch.atsc

alias

Source line 39

Alias of std.time.epoch.gps

std.time.epoch.bios

alias

Source line 31

Alias of std.time.epoch.dos

std.time.epoch.brew

alias

Source line 38

Alias of std.time.epoch.gps

std.time.epoch.clr

constant

Source line 26

Jan 01, 0001 AD

std.time.epoch.DaySeconds

container

Source line 151

seconds since start of day

Fields

secs: u17

std.time.epoch.DaySeconds.getHoursIntoDay

function

Source line 155

the number of hours past the start of the day (0 to 23)

pub fn getHoursIntoDay(self: DaySeconds) u5

Parameters

self: DaySeconds

std.time.epoch.DaySeconds.getMinutesIntoHour

function

Source line 159

the number of minutes past the hour (0 to 59)

pub fn getMinutesIntoHour(self: DaySeconds) u6

Parameters

self: DaySeconds

std.time.epoch.DaySeconds.getSecondsIntoMinute

function

Source line 163

the number of seconds past the start of the minute (0 to 59)

pub fn getSecondsIntoMinute(self: DaySeconds) u6

Parameters

self: DaySeconds

std.time.epoch.dos

constant

Source line 10

Jan 01, 1980 AD

std.time.epoch.epoch_year

constant

Source line 45

std.time.epoch.EpochDay

container

Source line 134

days since epoch Jan 1, 1970

Fields

day: u47

std.time.epoch.EpochDay.calculateYearDay

function

Source line 136

pub fn calculateYearDay(self: EpochDay) YearAndDay

Parameters

self: EpochDay

std.time.epoch.EpochSeconds

container

Source line 169

seconds since epoch Jan 1, 1970 at 12:00 AM

Fields

secs: u64

std.time.epoch.EpochSeconds.getDaySeconds

function

Source line 180

Returns the number of seconds into the day as DaySeconds. Use DaySeconds to get information about the time.

pub fn getDaySeconds(self: EpochSeconds) DaySeconds

Parameters

self: EpochSeconds

std.time.epoch.EpochSeconds.getEpochDay

function

Source line 174

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

Parameters

self: EpochSeconds

std.time.epoch.getDaysInMonth

function

Source line 89

Get the number of days in the given month and year

pub fn getDaysInMonth(year: Year, month: Month) u5

Parameters

year: Year
month: Month

std.time.epoch.getDaysInYear

function

Source line 63

pub fn getDaysInYear(year: Year) u9

Parameters

year: Year

std.time.epoch.go

alias

Source line 40

Alias of std.time.epoch.clr

std.time.epoch.gps

constant

Source line 24

Jan 06, 1980 AD

std.time.epoch.ios

constant

Source line 12

Jan 01, 2001 AD

std.time.epoch.isLeapYear

function

Source line 48

pub fn isLeapYear(year: Year) bool

Parameters

year: Year

Example usage

test isLeapYear {
    try testing.expectEqual(false, isLeapYear(2095));
    try testing.expectEqual(true, isLeapYear(2096));
    try testing.expectEqual(false, isLeapYear(2100));
    try testing.expectEqual(true, isLeapYear(2400));
}

std.time.epoch.jbase

alias

Source line 35

Alias of std.time.epoch.pickos

std.time.epoch.math

alias

Source line 5

Alias of std.math

std.time.epoch.Month

container

Source line 67

Fields

jan = 1
feb
mar
apr
may
jun
jul
aug
sep
oct
nov
dec

std.time.epoch.Month.numeric

function

Source line 83

return the numeric calendar value for the given month i.e. jan=1, feb=2, etc

pub fn numeric(self: Month) u4

Parameters

self: Month

std.time.epoch.MonthAndDay

container

Source line 128

Fields

month: Month
day_index: u5

std.time.epoch.morphos

alias

Source line 37

Alias of std.time.epoch.amiga

std.time.epoch.ntfs

alias

Source line 33

Alias of std.time.epoch.windows

std.time.epoch.ntp

alias

Source line 34

Alias of std.time.epoch.zos

std.time.epoch.openvms

constant

Source line 14

Nov 17, 1858 AD

std.time.epoch.os2

alias

Source line 30

Alias of std.time.epoch.dos

std.time.epoch.pickos

constant

Source line 22

Dec 31, 1967 AD

std.time.epoch.posix

constant

Source line 8

Jan 01, 1970 AD

std.time.epoch.secs_per_day

constant

Source line 46

u17

std.time.epoch.std

alias

Source line 3

Alias of std

std.time.epoch.testEpoch

function

Source line 185

fn testEpoch(secs: u64, expected_year_day: YearAndDay, expected_month_day: MonthAndDay, expected_day_seconds: struct { hours_into_day: u5, minutes_into_hour: u6, seconds_into_minute: u6, }) !void

Parameters

secs: u64
expected_year_day: YearAndDay
expected_month_day: MonthAndDay
expected_day_seconds: struct {
    /// 0 to 23
    hours_into_day: u5,
    /// 0 to 59
    minutes_into_hour: u6,
    /// 0 to 59
    seconds_into_minute: u6,
}

std.time.epoch.testing

alias

Source line 4

Alias of std.testing

std.time.epoch.unix

alias

Source line 28

Alias of std.time.epoch.posix

std.time.epoch.vfat

alias

Source line 32

Alias of std.time.epoch.dos

std.time.epoch.windows

constant

Source line 18

Jan 01, 1601 AD

std.time.epoch.Year

type

Source line 43

The type that holds the current year, i.e. 2016

std.time.epoch.YearAndDay

container

Source line 109

Fields

year: Year
day: u9

The number of days into the year (0 to 365)

std.time.epoch.YearAndDay.calculateMonthDay

function

Source line 114

pub fn calculateMonthDay(self: YearAndDay) MonthAndDay

Parameters

self: YearAndDay

std.time.epoch.zos

constant

Source line 16

Jan 01, 1900 AD

Source code

std/time/epoch.zig

//! Epoch reference times in terms of their difference from
//! UTC 1970-01-01 in seconds.
const std = @import("../std.zig");
const testing = std.testing;
const math = std.math;

/// Jan 01, 1970 AD
pub const posix = 0;
/// Jan 01, 1980 AD
pub const dos = 315532800;
/// Jan 01, 2001 AD
pub const ios = 978307200;
/// Nov 17, 1858 AD
pub const openvms = -3506716800;
/// Jan 01, 1900 AD
pub const zos = -2208988800;
/// Jan 01, 1601 AD
pub const windows = -11644473600;
/// Jan 01, 1978 AD
pub const amiga = 252460800;
/// Dec 31, 1967 AD
pub const pickos = -63244800;
/// Jan 06, 1980 AD
pub const gps = 315964800;
/// Jan 01, 0001 AD
pub const clr = -62135769600;

pub const unix = posix;
pub const android = posix;
pub const os2 = dos;
pub const bios = dos;
pub const vfat = dos;
pub const ntfs = windows;
pub const ntp = zos;
pub const jbase = pickos;
pub const aros = amiga;
pub const morphos = amiga;
pub const brew = gps;
pub const atsc = gps;
pub const go = clr;

/// The type that holds the current year, i.e. 2016
pub const Year = u16;

pub const epoch_year = 1970;
pub const secs_per_day: u17 = 24 * 60 * 60;

pub fn isLeapYear(year: Year) bool {
    if (@mod(year, 4) != 0)
        return false;
    if (@mod(year, 100) != 0)
        return true;
    return (0 == @mod(year, 400));
}

test isLeapYear {
    try testing.expectEqual(false, isLeapYear(2095));
    try testing.expectEqual(true, isLeapYear(2096));
    try testing.expectEqual(false, isLeapYear(2100));
    try testing.expectEqual(true, isLeapYear(2400));
}

pub fn getDaysInYear(year: Year) u9 {
    return if (isLeapYear(year)) 366 else 365;
}

pub const Month = enum(u4) {
    jan = 1,
    feb,
    mar,
    apr,
    may,
    jun,
    jul,
    aug,
    sep,
    oct,
    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 @backingInt(self);
    }
};

/// Get the number of days in the given month and year
pub fn getDaysInMonth(year: Year, month: Month) u5 {
    return switch (month) {
        .jan => 31,
        .feb => switch (isLeapYear(year)) {
            true => 29,
            false => 28,
        },
        .mar => 31,
        .apr => 30,
        .may => 31,
        .jun => 30,
        .jul => 31,
        .aug => 31,
        .sep => 30,
        .oct => 31,
        .nov => 30,
        .dec => 31,
    };
}

pub const YearAndDay = struct {
    year: Year,
    /// The number of days into the year (0 to 365)
    day: u9,

    pub fn calculateMonthDay(self: YearAndDay) MonthAndDay {
        var month: Month = .jan;
        var days_left = self.day;
        while (true) {
            const days_in_month = getDaysInMonth(self.year, month);
            if (days_left < days_in_month)
                break;
            days_left -= days_in_month;
            month = @as(Month, @fromBackingInt(@intCast(@backingInt(month) + 1)));
        }
        return .{ .month = month, .day_index = @as(u5, @intCast(days_left)) };
    }
};

pub const MonthAndDay = struct {
    month: Month,
    day_index: u5, // days into the month (0 to 30)
};

/// 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;
        while (true) {
            const year_size = getDaysInYear(year);
            if (year_day < year_size)
                break;
            year_day -= year_size;
            year += 1;
        }
        return .{ .year = year, .day = @as(u9, @intCast(year_day)) };
    }
};

/// seconds since start of day
pub const DaySeconds = struct {
    secs: u17, // max is 24*60*60 = 86400

    /// 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)));
    }
    /// 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)));
    }
    /// 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);
    }
};

/// seconds since epoch Jan 1, 1970 at 12:00 AM
pub const EpochSeconds = 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 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) };
    }
};

fn testEpoch(secs: u64, expected_year_day: YearAndDay, expected_month_day: MonthAndDay, expected_day_seconds: struct {
    /// 0 to 23
    hours_into_day: u5,
    /// 0 to 59
    minutes_into_hour: u6,
    /// 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());
    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 }, .{
        .month = .jan,
        .day_index = 0,
    }, .{ .hours_into_day = 0, .minutes_into_hour = 0, .seconds_into_minute = 0 });

    try testEpoch(31535999, .{ .year = 1970, .day = 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 }, .{
        .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 }, .{
        .month = .jul,
        .day_index = 0,
    }, .{ .hours_into_day = 17, .minutes_into_hour = 11, .seconds_into_minute = 13 });
}