Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.1

0.7.1 / src / clock / datetime.lucb

#==============================================================================================
#
#   datetime - Calendar dates and times of day
#
#   DESCRIPTION:
#       A DateTime: a date and time of day at a fixed offset from UTC, from the wall clock or
#       a timestamp, moved between offsets, compared, and written and read as ISO 8601.
#
#==============================================================================================

## A day of the week, numbered as ISO 8601 numbers them.
pub enum Weekday as u8:
    monday = 1
    tuesday = 2
    wednesday = 3
    thursday = 4
    friday = 5
    saturday = 6
    sunday = 7

## A date and time of day, in the years 1 to 9999, at a fixed offset from UTC. Two values
## for the same instant at different offsets differ as values; compare instants with
## `is_before` or `since`.
pub struct DateTime:
    ## The year, 1 to 9999.
    pub let year: i32
    ## The month, 1 to 12.
    pub let month: u8
    ## The day of the month, from 1.
    pub let day: u8
    ## The hour, 0 to 23.
    pub let hour: u8
    ## The minute, 0 to 59.
    pub let minute: u8
    ## The second, 0 to 59.
    pub let second: u8
    ## The nanoseconds past the second.
    pub let nanosecond: u32
    ## The offset east of UTC in seconds: 0 for UTC, 7200 for UTC+02:00.
    pub let offset: i32

    ## The given date and time, refusing one the calendar does not have.
    pub func init(year: i64, month: i64, day: i64, hour: i64 = 0, minute: i64 = 0, second: i64 = 0, nanosecond: i64 = 0, offset: i64 = 0) -> !:
        if year < 1 or year > 9999 or month < 1 or month > 12 or day < 1 or day > days_in_month(year, month):
            error(invalid, "the calendar has no such date")
        if hour < 0 or hour > 23 or minute < 0 or minute > 59 or second < 0 or second > 59 or nanosecond < 0 or nanosecond >= 1000000000:
            error(invalid, "a day has no such time")
        if offset <= -86400 or offset >= 86400:
            error(invalid, "an offset from UTC is less than a day")
        self.year = (i32)year
        self.month = (u8)month
        self.day = (u8)day
        self.hour = (u8)hour
        self.minute = (u8)minute
        self.second = (u8)second
        self.nanosecond = (u32)nanosecond
        self.offset = (i32)offset

    ## Now, in the system's local time zone.
    pub static func now() -> DateTime!:
        let (seconds, nanoseconds) = wall_clock()
        return try instant_at(seconds, nanoseconds, try local_offset(seconds))

    ## Now, in UTC.
    pub static func now_utc() -> DateTime!:
        let (seconds, nanoseconds) = wall_clock()
        return try instant_at(seconds, nanoseconds, 0)

    ## The UTC date and time `seconds` after 1970-01-01 00:00 UTC, as `timestamp` counts.
    pub static func from_timestamp(seconds: f64) -> DateTime!:
        if not (seconds >= -62135596800.0 and seconds < 253402300800.0):
            error(invalid, "the timestamp is outside the years 1 to 9999")
        let whole = (i64)seconds
        var floor = whole - 1 if (f64)whole > seconds else whole
        var nanoseconds = (i64)((seconds - (f64)floor) * 1000000000.0 + 0.5)
        if nanoseconds >= 1000000000:
            floor += 1
            nanoseconds -= 1000000000
        return try instant_at(floor, (u32)nanoseconds, 0)

    ## Read ISO 8601 text: `2026-10-04`, `2026-10-04T09:30`, `2026-10-04 09:30:15.25`, each
    ## with an optional `Z`, `+02:00` or `-0700`. A time without an offset is taken as UTC.
    pub static func parse(text: str) -> DateTime!:
        return try parse_iso(text)

    ## The day of the week.
    pub func weekday() -> Weekday:
        let days = days_from_civil((i64)self.year, (i64)self.month, (i64)self.day)
        return Weekday((u8)((days + 3) % 7 + 7) % 7 + 1)

    ## The day of the year, from 1.
    pub func day_of_year() -> i64:
        return days_from_civil((i64)self.year, (i64)self.month, (i64)self.day) - days_from_civil((i64)self.year, 1, 1) + 1

    ## Whole seconds since 1970-01-01 00:00 UTC, rounded down.
    pub func unix_seconds() -> i64:
        let days = days_from_civil((i64)self.year, (i64)self.month, (i64)self.day)
        return days * 86400 + (i64)self.hour * 3600 + (i64)self.minute * 60 + (i64)self.second - (i64)self.offset

    ## Seconds since 1970-01-01 00:00 UTC, with their fraction.
    pub func timestamp() -> f64:
        return (f64)self.unix_seconds() + (f64)self.nanosecond / 1000000000.0

    ## The same instant in UTC.
    pub func to_utc() -> DateTime!:
        return try instant_at(self.unix_seconds(), self.nanosecond, 0)

    ## The same instant in the system's local time zone.
    pub func to_local() -> DateTime!:
        let seconds = self.unix_seconds()
        return try instant_at(seconds, self.nanosecond, try local_offset(seconds))

    ## The same instant at `offset` seconds east of UTC.
    pub func at_offset(offset: i64) -> DateTime!:
        if offset <= -86400 or offset >= 86400:
            error(invalid, "an offset from UTC is less than a day")
        return try instant_at(self.unix_seconds(), self.nanosecond, (i32)offset)

    ## The date and time `span` later, or earlier for a negative span, at the same offset.
    pub func plus(span: Duration) -> DateTime!:
        let total = (i64)self.nanosecond + span.nanoseconds % nanoseconds_per_second
        let carry = floor_divide(total, nanoseconds_per_second)
        let seconds = self.unix_seconds() + span.nanoseconds // nanoseconds_per_second + carry
        return try instant_at(seconds, (u32)(total - carry * nanoseconds_per_second), self.offset)

    ## The time from `earlier` to this one; negative when `earlier` is later.
    pub func since(earlier: DateTime) -> Duration:
        let seconds = self.unix_seconds() - earlier.unix_seconds()
        return Duration(nanoseconds = seconds * nanoseconds_per_second + (i64)self.nanosecond - (i64)earlier.nanosecond)

    ## Whether this is an earlier instant than `other`, whatever their offsets.
    pub func is_before(other: DateTime) -> bool:
        return self.since(other).nanoseconds < 0

    ## ISO 8601 text: `2026-10-04T09:30:15Z`, with a fraction of a second when there is one
    ## and the offset as `+02:00` when it is not UTC.
    pub func text() -> interop.Owned[str]!:
        var buffer: u8[48]
        var used: usize = 0
        put_date(buffer, &used, self)
        buffer[used] = 'T'
        used += 1
        put_time(buffer, &used, self)
        put_offset(buffer, &used, self.offset)
        return try owned.copy_text((str)buffer[..<used])

    ## The date alone: `2026-10-04`.
    pub func date_text() -> interop.Owned[str]!:
        var buffer: u8[16]
        var used: usize = 0
        put_date(buffer, &used, self)
        return try owned.copy_text((str)buffer[..<used])

## The date and time at `offset` of the instant `seconds` and `nanoseconds` past 1970 UTC.
func instant_at(seconds: i64, nanoseconds: u32, offset: i32) -> DateTime!:
    let shifted = seconds + (i64)offset
    let days = floor_divide(shifted, 86400)
    let rest = shifted - days * 86400
    let (year, month, day) = civil_from_days(days)
    if year < 1 or year > 9999:
        error(invalid, "the date is outside the years 1 to 9999")
    return try DateTime(year, month, day, rest // 3600, rest % 3600 // 60, rest % 60, (i64)nanoseconds, (i64)offset)

# mark: ISO 8601 text =========================================================================

func put_digits(buffer: u8[], used: usize*, value: i64, width: usize):
    var index = width
    var rest = value
    while index > 0:
        index -= 1
        buffer[*used + index] = (u8)(rest % 10) + '0'
        rest = rest // 10
    *used += width

func put_date(buffer: u8[], used: usize*, value: DateTime):
    put_digits(buffer, used, (i64)value.year, 4)
    buffer[*used] = '-'
    *used += 1
    put_digits(buffer, used, (i64)value.month, 2)
    buffer[*used] = '-'
    *used += 1
    put_digits(buffer, used, (i64)value.day, 2)

func put_time(buffer: u8[], used: usize*, value: DateTime):
    put_digits(buffer, used, (i64)value.hour, 2)
    buffer[*used] = ':'
    *used += 1
    put_digits(buffer, used, (i64)value.minute, 2)
    buffer[*used] = ':'
    *used += 1
    put_digits(buffer, used, (i64)value.second, 2)
    if value.nanosecond != 0:
        buffer[*used] = '.'
        *used += 1
        let fraction = (i64)value.nanosecond
        if fraction % 1000000 == 0:
            put_digits(buffer, used, fraction // 1000000, 3)
        elif fraction % 1000 == 0:
            put_digits(buffer, used, fraction // 1000, 6)
        else:
            put_digits(buffer, used, fraction, 9)

func put_offset(buffer: u8[], used: usize*, offset: i32):
    if offset == 0:
        buffer[*used] = 'Z'
        *used += 1
        return
    buffer[*used] = '+' if offset > 0 else '-'
    *used += 1
    let minutes = (i64)(offset if offset > 0 else -offset) // 60
    put_digits(buffer, used, minutes // 60, 2)
    buffer[*used] = ':'
    *used += 1
    put_digits(buffer, used, minutes % 60, 2)

## Reads ISO 8601 text left to right.
struct Reader:
    var text: const u8[]
    var at: usize

    func done() -> bool:
        return self.at == self.text.length

    func peek() -> u8:
        return self.text[self.at] if self.at < self.text.length else 0

    func take(byte: u8) -> bool:
        if self.peek() != byte or self.done():
            return false
        self.at += 1
        return true

    ## Exactly `width` digits.
    func digits(width: usize) -> i64!:
        var value: i64 = 0
        for index in 0..<width:
            _ = index
            let byte = self.peek()
            if self.done() or byte < '0' or byte > '9':
                error(invalid, "the text is not an ISO 8601 date and time")
            value = value * 10 + (i64)(byte - '0')
            self.at += 1
        return value

func parse_iso(text: str) -> DateTime!:
    var reader = Reader(text = text.bytes, at = 0)
    let year = try reader.digits(4)
    var month: i64 = 1
    var day: i64 = 1
    if not reader.take('-'):
        error(invalid, "the text is not an ISO 8601 date and time")
    month = try reader.digits(2)
    if not reader.take('-'):
        error(invalid, "the text is not an ISO 8601 date and time")
    day = try reader.digits(2)
    var hour: i64 = 0
    var minute: i64 = 0
    var second: i64 = 0
    var nanosecond: i64 = 0
    var offset: i64 = 0
    if reader.take('T') or reader.take('t') or reader.take(' '):
        hour = try reader.digits(2)
        if not reader.take(':'):
            error(invalid, "the text is not an ISO 8601 date and time")
        minute = try reader.digits(2)
        if reader.take(':'):
            second = try reader.digits(2)
            if reader.take('.') or reader.take(','):
                var scale: i64 = 100000000
                var count: usize = 0
                while not reader.done() and reader.peek() >= '0' and reader.peek() <= '9':
                    nanosecond += (i64)(reader.peek() - '0') * scale
                    scale = scale // 10
                    reader.at += 1
                    count += 1
                if count == 0 or count > 9:
                    error(invalid, "a fraction of a second has one to nine digits")
        if reader.take('Z') or reader.take('z'):
            offset = 0
        elif reader.peek() == '+' or reader.peek() == '-':
            let sign: i64 = 1 if reader.peek() == '+' else -1
            reader.at += 1
            let hours = try reader.digits(2)
            var minutes: i64 = 0
            if reader.take(':'):
                minutes = try reader.digits(2)
            elif not reader.done():
                minutes = try reader.digits(2)
            if hours > 23 or minutes > 59:
                error(invalid, "an offset from UTC is less than a day")
            offset = sign * (hours * 3600 + minutes * 60)
    if not reader.done():
        error(invalid, "the text is not an ISO 8601 date and time")
    return try DateTime(year, month, day, hour, minute, second, nanosecond, offset)

test "dates format and parse as ISO 8601":
    let moment = try DateTime(2026, 10, 4, 9, 30, 15, 250000000, 7200)
    let text = try moment.text()
    defer text.release()
    assert(text.value == "2026-10-04T09:30:15.250+02:00")
    let back = try DateTime.parse(text.value)
    assert(back == moment and back.unix_seconds() == 1791099015)
    assert(try DateTime.parse("2026-10-04") == try DateTime(2026, 10, 4))
    let parsed = try (try DateTime.parse("2026-10-04 07:30Z")).to_utc()
    assert(parsed == try (try moment.to_utc()).plus(Duration.of_milliseconds(-15250)))
    assert((try DateTime.parse("1969-12-31T23:59:59-0700")).unix_seconds() == 25199)
    assert(moment.weekday() == Weekday.sunday and moment.day_of_year() == 277)
    var refused = 0
    for bad in ["2026-02-30", "2026-10-04T24:00", "2026-10-4", "2026-10-04T09:30:15.", "2026-10-04 extra"]:
        _ = DateTime.parse(bad) catch failure:
            assert(failure.code == invalid)
            refused += 1
            recover moment
    assert(refused == 5)

test "instants move between offsets and timestamps":
    let epoch = try DateTime.from_timestamp(0.0)
    let epoch_text = try epoch.text()
    defer epoch_text.release()
    assert(epoch_text.value == "1970-01-01T00:00:00Z" and epoch.weekday() == Weekday.thursday)
    let before = try DateTime.from_timestamp(-0.5)
    assert(before.year == 1969 and before.second == 59 and before.nanosecond == 500000000)
    let shifted = try epoch.at_offset(-18000)
    assert(shifted.day == 31 and shifted.hour == 19 and shifted.since(epoch).nanoseconds == 0)
    let later = try epoch.plus(try Duration.of_seconds(86400.25))
    assert(later.day == 2 and later.nanosecond == 250000000 and epoch.is_before(later))
    let current = try DateTime.now()
    assert(current.year >= 2026 and (try current.to_utc()).offset == 0)