# Lyng time functions

Lyng date and time support requires importing `lyng.time`. The module provides four related types:

- `Instant` for absolute timestamps.
- `Date` for calendar dates without time-of-day or timezone.
- `DateTime` for calendar-aware points in time in a specific timezone.
- `Duration` for absolute elapsed time.

## Time instant: `Instant`

`Instant` represents some moment of time independently of the calendar. It is similar to SQL `TIMESTAMP`
or Kotlin `Instant`.

### Constructing and converting

    import lyng.time

    val t1 = Instant()
    val t2 = Instant(1704110400)
    val t3 = Instant("2024-01-01T12:00:00.123456Z")

    val t4 = t3.truncateToMinute()
    assertEquals("2024-01-01T12:00:00Z", t4.toRFC3339())

    val dt = t3.toDateTime("+02:00")
    assertEquals(14, dt.hour)

    val d = t3.toDate("Z")
    assertEquals(Date(2024, 1, 1), d)

### Instant members

| member                         | description                                          |
|--------------------------------|------------------------------------------------------|
| epochSeconds: Real             | offset in seconds since Unix epoch                   |
| epochWholeSeconds: Int         | whole seconds since Unix epoch                       |
| nanosecondsOfSecond: Int       | nanoseconds within the current second                |
| isDistantFuture: Bool          | true if it is `Instant.distantFuture`                |
| isDistantPast: Bool            | true if it is `Instant.distantPast`                  |
| truncateToMinute(): Instant    | truncate to minute precision                         |
| truncateToSecond(): Instant    | truncate to second precision                         |
| truncateToMillisecond(): Instant | truncate to millisecond precision                  |
| truncateToMicrosecond(): Instant | truncate to microsecond precision                  |
| toRFC3339(): String            | format as RFC3339 string in UTC                      |
| toDateTime(tz?): DateTime      | localize to a timezone                               |
| toDate(tz?): Date              | convert to a calendar date in a timezone             |

## Calendar date: `Date`

`Date` represents a pure calendar date. It has no time-of-day and no attached timezone. Use it for values
like birthdays, due dates, invoice dates, and SQL `DATE` columns.

### Constructing

    import lyng.time

    val today = Date()
    val d1 = Date(2026, 4, 15)
    val d2 = Date("2024-02-29")
    val d3 = Date.parseIso("2024-02-29")
    val d4 = Date(DateTime(2024, 5, 20, 15, 30, 45, "+02:00"))
    val d5 = Date(Instant("2024-01-01T23:30:00Z"), "+02:00")

### Date members

| member                         | description                                                |
|--------------------------------|------------------------------------------------------------|
| year: Int                      | year component                                             |
| month: Int                     | month component (1..12)                                    |
| day: Int                       | day of month (alias `dayOfMonth`)                          |
| dayOfWeek: Int                 | day of week (1=Monday, 7=Sunday)                           |
| dayOfYear: Int                 | day of year (1..365/366)                                   |
| isLeapYear: Bool               | whether this date is in a leap year                        |
| lengthOfMonth: Int             | number of days in this month                               |
| lengthOfYear: Int              | 365 or 366                                                 |
| toIsoString(): String          | ISO `YYYY-MM-DD` string                                    |
| toSortableString(): String     | alias to `toIsoString()`                                   |
| toDateTime(tz="Z"): DateTime  | start-of-day `DateTime` in the specified timezone          |
| atStartOfDay(tz="Z"): DateTime | alias to `toDateTime()`                                  |
| addDays(n): Date               | add or subtract calendar days                              |
| addMonths(n): Date             | add or subtract months, normalizing end-of-month           |
| addYears(n): Date              | add or subtract years                                      |
| daysUntil(other): Int          | calendar days until `other`                                |
| daysSince(other): Int          | calendar days since `other`                                |
| static today(tz?): Date        | today in the specified timezone                            |
| static parseIso(s): Date       | parse ISO `YYYY-MM-DD`                                     |

### Date arithmetic

`Date` supports only whole-day arithmetic. This is deliberate: calendar dates should not silently accept
sub-day durations.

    import lyng.time

    val d1 = Date(2026, 4, 15)
    val d2 = d1.addDays(10)

    assertEquals(Date(2026, 4, 25), d2)
    assertEquals(Date(2026, 4, 18), d1 + 3.days)
    assertEquals(Date(2026, 4, 12), d1 - 3.days)
    assertEquals(10, d1.daysUntil(d2))
    assertEquals(10, d2.daysSince(d1))
    assertEquals(10, d2 - d1)

### Date conversions

    import lyng.time

    val i = Instant("2024-01-01T23:30:00Z")
    assertEquals(Date(2024, 1, 1), i.toDate("Z"))
    assertEquals(Date(2024, 1, 2), i.toDate("+02:00"))

    val dt = DateTime(2024, 5, 20, 15, 30, 45, "+02:00")
    assertEquals(Date(2024, 5, 20), dt.date)
    assertEquals(Date(2024, 5, 20), dt.toDate())
    assertEquals(DateTime(2024, 5, 20, 0, 0, 0, "Z"), Date(2024, 5, 20).toDateTime("Z"))
    assertEquals(DateTime(2024, 5, 20, 0, 0, 0, "+02:00"), Date(2024, 5, 20).atStartOfDay("+02:00"))

## Calendar time: `DateTime`

`DateTime` represents a point in time in a specific timezone. It provides access to calendar components
such as year, month, day, and hour.

### Constructing

    import lyng.time

    val now = DateTime.now()
    val offsetTime = DateTime.now("+02:00")
    val dt = Instant().toDateTime("Z")
    val dt2 = DateTime(2024, 1, 1, 12, 0, 0, "Z")
    val dt3 = DateTime.parseRFC3339("2024-01-01T12:00:00+02:00")

### DateTime members

| member                           | description                                   |
|----------------------------------|-----------------------------------------------|
| year: Int                        | year component                                |
| month: Int                       | month component (1..12)                       |
| day: Int                         | day of month (alias `dayOfMonth`)             |
| hour: Int                        | hour component (0..23)                        |
| minute: Int                      | minute component (0..59)                      |
| second: Int                      | second component (0..59)                      |
| dayOfWeek: Int                   | day of week (1=Monday, 7=Sunday)              |
| timeZone: String                 | timezone ID string                            |
| date: Date                       | calendar date component                       |
| toInstant(): Instant             | convert back to absolute Instant              |
| toDate(): Date                   | extract the calendar date in this timezone    |
| toUTC(): DateTime                | shortcut to convert to UTC                    |
| toTimeZone(tz): DateTime         | convert to another timezone                   |
| addMonths(n): DateTime           | add/subtract months (normalizes end of month) |
| addYears(n): DateTime            | add/subtract years                            |
| toRFC3339(): String              | format with timezone offset                   |
| static now(tz?): DateTime        | create DateTime with current time             |
| static parseRFC3339(s): DateTime | parse RFC3339 string                          |

### Arithmetic and normalization

`DateTime` handles calendar arithmetic correctly:

    import lyng.time

    val leapDay = Instant("2024-02-29T12:00:00Z").toDateTime("Z")
    val nextYear = leapDay.addYears(1)
    assertEquals(28, nextYear.day)

# `Duration` class

`Duration` represents absolute elapsed time between two instants.

    import lyng.time

    val t1 = Instant()
    delay(1.millisecond)
    val t2 = Instant()

    assert(t2 - t1 >= 1.millisecond)
    assert(t2 - t1 < 100.millisecond)
    >>> void

Duration values can be created from numbers using extensions on `Int` and `Real`:

- `n.millisecond`, `n.milliseconds`
- `n.second`, `n.seconds`
- `n.minute`, `n.minutes`
- `n.hour`, `n.hours`
- `n.day`, `n.days`

Larger units like months or years are calendar-dependent and are intentionally not part of `Duration`.

Each duration instance can be converted to numbers in these units:

- `d.microseconds`
- `d.milliseconds`
- `d.seconds`
- `d.minutes`
- `d.hours`
- `d.days`

Example:

    import lyng.time

    assertEquals(60, 1.minute.seconds)
    assertEquals(10.milliseconds, 0.01.seconds)
    >>> void

# Utility functions

## `delay(duration: Duration)`

Suspends the current coroutine for at least the specified duration.