Skip to content

date.md

Latest commit

 

History

History
200 lines (147 loc) · 5.56 KB

date.md

File metadata and controls

200 lines (147 loc) · 5.56 KB
Raw

Date Module

The date module works with Unix timestamps (seconds since 1970-01-01 00:00:00 UTC) and provides formatting, parsing, component extraction, arithmetic, and range helpers.

Import

import date;

Getting the Current Time

Function Signature Description
date.now int() Current time as Unix timestamp (seconds)
date.now_millis int() Current time in milliseconds since epoch 
int ts = date.now();
output(ts, int);  // e.g. 1716400000

Formatting Timestamps

Function Signature Description
date.format_iso string(int ts) ISO 8601: "2024-05-22T14:30:00"
date.format_date string(int ts) Date only: "2024-05-22"
date.format_time string(int ts) Time only: "14:30:00"
date.format string(int ts, string fmt) Custom strftime format string 
int now = date.now();
output(date.format_iso(now), string);    // 2024-05-22T14:30:00
output(date.format_date(now), string);   // 2024-05-22
output(date.format_time(now), string);   // 14:30:00

// Custom format using strftime patterns
output(date.format(now, "%d/%m/%Y"), string);  // 22/05/2024
output(date.format(now, "%A, %B %d"), string); // Wednesday, May 22

Parsing Strings to Timestamps

Function Signature Description
date.parse_iso int(string iso) Parse ISO 8601 → timestamp
date.parse int(string date_str, string fmt) Parse with custom strptime format 
int ts = date.parse_iso("2024-12-25T00:00:00");
output(date.format_date(ts), string);  // 2024-12-25

int ts2 = date.parse("25/12/2024", "%d/%m/%Y");

Extracting Components

Function Signature Returns
date.get_year int(int ts) Full year (e.g. 2024)
date.get_month int(int ts) Month 1–12
date.get_day int(int ts) Day of month 1–31
date.get_hour int(int ts) Hour 0–23
date.get_minute int(int ts) Minute 0–59
date.get_second int(int ts) Second 0–59
date.get_weekday int(int ts) Day of week: 0=Sunday, 6=Saturday
date.get_weekday_name string(int ts) e.g. "Monday"
date.get_month_name string(int ts) e.g. "January" 
int ts = date.now();
int year  = date.get_year(ts);
int month = date.get_month(ts);
int day   = date.get_day(ts);

output(year, int);
output(date.get_month_name(ts), string);
output(date.get_weekday_name(ts), string);

Date Arithmetic

Add or subtract time from a timestamp:

Function Signature Description
date.add_seconds int(int ts, int n) Add n seconds
date.add_minutes int(int ts, int n) Add n minutes
date.add_hours int(int ts, int n) Add n hours
date.add_days int(int ts, int n) Add n days

Pass a negative number to subtract:

int now  = date.now();
int tomorrow  = date.add_days(now, 1);
int yesterday = date.add_days(now, -1);
int next_hour = date.add_hours(now, 1);
int in_30_min = date.add_minutes(now, 30);

output(date.format_date(tomorrow), string);

Difference Between Timestamps

Function Signature Description
date.diff_seconds int(int ts1, int ts2) ts1 - ts2 in seconds
date.diff_minutes int(int ts1, int ts2) ts1 - ts2 in minutes
date.diff_hours int(int ts1, int ts2) ts1 - ts2 in hours
date.diff_days int(int ts1, int ts2) ts1 - ts2 in days 
int start = date.parse_iso("2024-01-01T00:00:00");
int end   = date.parse_iso("2024-12-31T00:00:00");

int days = date.diff_days(end, start);
output(days, int);  // 365

Calendar Helpers

Function Signature Description
date.is_leap_year int(int ts) 1 if the year of ts is a leap year
date.days_in_month int(int ts) Number of days in the month of ts
date.start_of_day int(int ts) Timestamp at 00:00:00 of the same day
date.end_of_day int(int ts) Timestamp at 23:59:59 of the same day
date.start_of_month int(int ts) First day of the month at 00:00:00
date.end_of_month int(int ts) Last day of the month at 23:59:59 
int now = date.now();

if (date.is_leap_year(now) == 1) {
    output("This is a leap year", string);
}

int dim = date.days_in_month(now);
output(dim, int);

int month_start = date.start_of_month(now);
int month_end   = date.end_of_month(now);
output(date.format_date(month_start), string);
output(date.format_date(month_end), string);

Complete Example

import date;

void main() {
    int now = date.now();

    output("Current time:", string);
    output(date.format_iso(now), string);

    output("Day: " + date.get_weekday_name(now), string);
    output("Month: " + date.get_month_name(now), string);

    // Days until end of year
    int year     = date.get_year(now);
    string eoy_s = int_to_string(year) + "-12-31T23:59:59";
    int eoy      = date.parse_iso(eoy_s);
    int remaining = date.diff_days(eoy, now);
    output("Days left in year: " + int_to_string(remaining), string);

    // Is it a leap year?
    if (date.is_leap_year(now) == 1) {
        output("This is a leap year", string);
    }
}

See Also