Rill v0.13 Reference

Standard library · Time

time/date

Imported as import "time/date" as date, its names are then date.…. Every signature below is the one the checker infers.

Civil dates and times, in UTC and nothing else.

A Date is a year, a month and a day on the proleptic Gregorian calendar; a DateTime is one with a time of day. Both convert to and from a count — days since 1970-01-01 for a date, seconds since 1970-01-01T00:00:00Z for a date and time — and it is on the counts that arithmetic is done, so adding a day never lands on the 31st of February. ISO 8601 is the one text form: 2026-09-14 and 2026-09-14T21:03:00Z, read and written.

No time zones and no leap seconds: what a machine's clock says in UTC is what this handles, and a local time is the program's to make by adding an offset it knows.

today = date.today()
due = date.add_days(date.make(2026, 9, 14)?, 30)
due                                     # => 2026-10-14
date.parse("2026-02-29")                # => Err(February 2026 has 28 days, not 29)
date.weekday(date.make(2026, 9, 14)?)   # => 1

Types

Date

  • Date(year: Int, month: Int, day: Int)

DateTime

  • DateTime(date: Date, hour: Int, minute: Int, second: Int)

Implementations

  • impl Show(Date)
  • impl Show(DateTime)
  • impl Ord(Date)
  • impl Ord(DateTime)

Functions

fn make(y: Int, m: Int, d: Int) -> Result(Date, Str)

A date that exists, or why not.

date.make(2024, 2, 29)   # => Ok(2024-02-29)
date.make(2023, 2, 29)   # => Err(February 2023 has 28 days, not 29)

fn make_time(dt: Date, h: Int, mi: Int, s: Int) -> Result(DateTime, Str)

date.make_time(date.make(2026, 9, 14)?, 21, 3, 0)    # => Ok(2026-09-14T21:03:00Z)
date.make_time(date.make(2026, 9, 14)?, 24, 0, 0)    # => Err(hour 24 is not one of 0..23)

fn now() -> DateTime

The date and time the wall clock says, in UTC.

date.to_seconds(date.now()) > 1700000000   # => true

fn today() -> Date

date.today().year >= 2026   # => true

fn is_leap(y: Int) -> Bool

date.is_leap(2024)   # => true
date.is_leap(1900)   # => false
date.is_leap(2000)   # => true

fn days_in_month(y: Int, m: Int) -> Int

date.days_in_month(2024, 2)   # => 29
date.days_in_month(2026, 4)   # => 30

fn month_name(m: Int) -> Str

date.month_name(9)   # => September

fn weekday_name(w: Int) -> Str

date.weekday_name(0)   # => Sunday

fn to_days(d: Date) -> Int

Days since 1970-01-01; negative before it.

date.to_days(date.make(1970, 1, 2)?)    # => 1
date.to_days(date.make(1969, 12, 31)?)  # => -1

fn from_days(days: Int) -> Date

date.from_days(20000)   # => 2024-10-04

fn to_seconds(t: DateTime) -> Int

Seconds since 1970-01-01T00:00:00Z.

date.to_seconds(date.parse_time("1970-01-01T00:01:00Z")?)   # => 60

fn from_seconds(secs: Int) -> DateTime

date.from_seconds(1700000000)   # => 2023-11-14T22:13:20Z

fn weekday(d: Date) -> Int

0 is Sunday, 6 is Saturday. 1970-01-01 was a Thursday.

date.weekday(date.make(1970, 1, 1)?)   # => 4

fn day_of_year(d: Date) -> Int

1..366.

date.day_of_year(date.make(2026, 12, 31)?)   # => 365

fn add_days(d: Date, n: Int) -> Date

date.add_days(date.make(2026, 2, 27)?, 3)   # => 2026-03-02

fn add_seconds(t: DateTime, n: Int) -> DateTime

date.add_seconds(date.parse_time("2026-12-31T23:59:59Z")?, 1)   # => 2027-01-01T00:00:00Z

fn days_between(a: Date, b: Date) -> Int

b - a in days; negative when b is earlier.

date.days_between(date.make(2026, 1, 1)?, date.make(2026, 3, 1)?)   # => 59
date.days_between(date.make(2026, 3, 1)?, date.make(2026, 1, 1)?)   # => -59

fn seconds_between(a: DateTime, b: DateTime) -> Int

date.seconds_between(date.parse_time("2026-01-01T00:00:00Z")?, date.parse_time("2026-01-01T01:00:00Z")?)   # => 3600

fn add_months(d: Date, n: Int) -> Date

The same day n months on, clamped to the month's length: January 31st plus a month is February 28th (or 29th), as a calendar would have it.

date.add_months(date.make(2026, 1, 31)?, 1)   # => 2026-02-28
date.add_months(date.make(2026, 1, 31)?, -2)  # => 2025-11-30

fn iso(d: Date) -> Str

date.iso(date.make(2026, 9, 4)?)   # => 2026-09-04

fn iso_time(t: DateTime) -> Str

date.iso_time(date.make_time(date.make(2026, 9, 4)?, 7, 5, 9)?)   # => 2026-09-04T07:05:09Z

fn parse(s: Str) -> Result(Date, Str)

2026-09-14, and nothing else.

date.parse("2026-09-14")   # => Ok(2026-09-14)
date.parse("14/09/2026")   # => Err(a date is written `YYYY-MM-DD`, not `14/09/2026`)

fn parse_time(s: Str) -> Result(DateTime, Str)

2026-09-14T21:03:00Z; the Z may be left off, and means UTC either way.

date.parse_time("2026-09-14T21:03:00Z")   # => Ok(2026-09-14T21:03:00Z)
date.parse_time("2026-09-14T21:03:00")    # => Ok(2026-09-14T21:03:00Z)

Tests

  • test_epoch_and_back
  • test_leap_years_and_months
  • test_weekday_and_arithmetic
  • test_text