Tokamak

Appearance

Time ​

Date and time manipulation based on the Rata Die calendar algorithm.

Types ​

Date ​

zig
pub const Date = struct {
    year: i32,
    month: u8,
    day: u8,
};

Represents a calendar date (year, month, day).

Time ​

zig
pub const Time = struct {
    epoch: i64,
};

Represents a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).

Date API ​

Construction ​

zig
Date.ymd(year: i32, month: u8, day: u8) Date

Create date from year, month, day.

zig
Date.parse(str: []const u8) !Date

Parse date from ISO 8601 string ("YYYY-MM-DD").

zig
Date.today() Date
Date.yesterday() Date
Date.tomorrow() Date

Get current/relative dates.

zig
Date.startOf(unit: DateUnit) Date
Date.endOf(unit: DateUnit) Date

Get start/end of current period.

Methods ​

zig
date.add(unit: DateUnit, amount: i64) Date

Add or subtract date units. Units: .day, .month, .year.

Month-end dates are clamped when adding months:

zig
Date.ymd(2024, 1, 31).add(.month, 1)  // 2024-02-29
zig
date.setStartOf(unit: DateUnit) Date
date.setEndOf(unit: DateUnit) Date

Set to start or end of period.

zig
date.dayOfWeek() u8

Get day of week (0 = Monday, 6 = Sunday).

zig
date.cmp(other: Date) std.math.Order

Compare dates (returns .lt, .eq, or .gt).

zig
date.format(writer: anytype) !void

Format as "YYYY-MM-DD". Use with {f} format specifier.

Time API ​

Construction ​

zig
Time.unix(epoch: i64) Time

Create from Unix timestamp.

zig
Time.now() Time

Get current time.

zig
Time.today() Time
Time.tomorrow() Time

Get midnight today/tomorrow.

zig
Time.startOf(unit: TimeUnit) Time
Time.endOf(unit: TimeUnit) Time

Get start/end of current period.

Component Access ​

zig
time.date() Date

Extract date part.

zig
time.hour() u32
time.minute() u32
time.second() u32

Get time-of-day components (0-23, 0-59, 0-59).

Component Modification ​

zig
time.setDate(date: Date) Time

Set date while preserving time-of-day.

zig
time.setHour(hr: u32) Time
time.setMinute(min: u32) Time
time.setSecond(sec: u32) Time

Set specific time components.

Arithmetic ​

zig
time.add(unit: enum, amount: i64) Time

Add or subtract time units. Units:

  • .seconds
  • .minutes
  • .hours
  • .days
  • .months
  • .years
zig
time.setStartOf(unit: TimeUnit) Time
time.setEndOf(unit: TimeUnit) Time

Set to start or end of period. Units: .second, .minute, .hour, .day, .month, .year.

zig
time.next(unit: enum) Time

Jump to start of next period. Units: .second, .minute, .hour, .day.

zig
time.format(writer: anytype) !void

Format as "YYYY-MM-DD HH:MM:SS UTC". Use with {f} format specifier.

Enums ​

zig
pub const TimeUnit = enum { second, minute, hour, day, month, year };
pub const DateUnit = enum { day, month, year };

Functions ​

zig
pub fn isLeapYear(year: i32) bool

Check if year is a leap year.

Examples ​

Basic Usage ​

zig
// Create and manipulate times
const t1 = tk.time.Time.unix(1234567890);
const t2 = t1.setHour(10).setMinute(15).setSecond(45);
const t3 = t2.add(.hours, 14).add(.minutes, 46);

// Format output
try writer.print("{f}", .{t3});  // "2009-02-14 01:02:03 UTC"

Period Boundaries ​

zig
const now = tk.time.Time.now();

// Start of periods
const day_start = now.setStartOf(.day);
const month_start = now.setStartOf(.month);
const year_start = now.setStartOf(.year);

// End of periods
const day_end = now.setEndOf(.day);
const month_end = now.setEndOf(.month);

Date Ranges ​

zig
const start = tk.time.Date.ymd(2024, 1, 1);
const end = tk.time.Date.ymd(2024, 1, 31);

var current = start;
while (current.cmp(end) != .gt) {
    // Process date
    current = current.add(.day, 1);
}

Notes ​

Limitations

  • UTC only - No timezone support
  • Second precision - No subsecond precision
  • Fixed format - No custom formatting (always ISO 8601)

Leap Year Handling

Leap years are automatically handled in all date operations. Month-end dates are clamped when necessary to ensure valid dates.