# time

> Time and dates — clock, date components, timers/sleep, durations, and formatting, organized into submodules.

# time

The `time` module groups clock readings, date-component extraction, sleeping, durations, and formatting into five submodules, plus a few top-level shortcuts. Timestamps are Unix seconds and all components are computed in UTC. Import it with `import time`.

## time.clock

| Function | Signature | Description |
| --- | --- | --- |
| `now` | `time.clock.now() → string` | current time as an RFC3339 string |
| `unix` | `time.clock.unix() → int` | current time in Unix seconds |
| `unixMilli` | `time.clock.unixMilli() → int` | current time in Unix milliseconds |
| `unixMicro` | `time.clock.unixMicro() → int` | current time in Unix microseconds |
| `unixNano` | `time.clock.unixNano() → int` | current time in Unix nanoseconds |

## time.date

| Function | Signature | Description |
| --- | --- | --- |
| `year` | `time.date.year(ts: int) → int` | year of the timestamp |
| `month` | `time.date.month(ts: int) → int` | month, 1–12 |
| `day` | `time.date.day(ts: int) → int` | day of month |
| `hour` | `time.date.hour(ts: int) → int` | hour, 0–23 |
| `minute` | `time.date.minute(ts: int) → int` | minute, 0–59 |
| `second` | `time.date.second(ts: int) → int` | second, 0–59 |
| `weekday` | `time.date.weekday(ts: int) → string` | weekday name, e.g. "Monday" |
| `isLeapYear` | `time.date.isLeapYear(year: int) → bool` | true if the year is a leap year |
| `fromParts` | `time.date.fromParts(year: int, month: int, day: int, hour: int, min: int, sec: int) → int` | build a Unix timestamp from UTC components |

## time.timer

| Function | Signature | Description |
| --- | --- | --- |
| `sleep` | `time.timer.sleep(ms: int) → void` | block the current execution for `ms` milliseconds |
| `since` | `time.timer.since(ts: int) → int` | milliseconds elapsed since `ts` |
| `until` | `time.timer.until(ts: int) → int` | milliseconds remaining until `ts` |

## time.duration

| Function | Signature | Description |
| --- | --- | --- |
| `parse` | `time.duration.parse(s: string) → int` | parse a Go duration string (e.g. "1h30m") into milliseconds; 0 on error |
| `format` | `time.duration.format(ms: int) → string` | format milliseconds as a duration string |
| `seconds` | `time.duration.seconds(n: int) → int` | `n` seconds in milliseconds |
| `minutes` | `time.duration.minutes(n: int) → int` | `n` minutes in milliseconds |
| `hours` | `time.duration.hours(n: int) → int` | `n` hours in milliseconds |
| `days` | `time.duration.days(n: int) → int` | `n` days in milliseconds |

## time.format

| Function | Signature | Description |
| --- | --- | --- |
| `rfc3339` | `time.format.rfc3339(ts: int) → string` | format as RFC3339 |
| `rfc1123` | `time.format.rfc1123(ts: int) → string` | format as RFC1123 |
| `date` | `time.format.date(ts: int) → string` | format as `2006-01-02` |
| `time` | `time.format.time(ts: int) → string` | format as `15:04:05` |
| `datetime` | `time.format.datetime(ts: int) → string` | format as `2006-01-02 15:04:05` |
| `custom` | `time.format.custom(ts: int, layout: string) → string` | format with a Go layout string |

## Top-level shortcuts

| Function | Signature | Description |
| --- | --- | --- |
| `now` | `time.now() → string` | current time as RFC3339 |
| `unix` | `time.unix() → int` | current time in Unix seconds |
| `sleep` | `time.sleep(ms: int) → void` | block for `ms` milliseconds |
| `parse` | `time.parse(s: string) → int` | parse an RFC3339 string into a Unix timestamp; 0 on error |

## Example

```goost
import time

// stamp "now", then break it into parts
let ts = time.clock.unix()
print(time.format.datetime(ts))           // 2026-05-29 14:03:21
print(time.date.weekday(ts))              // Friday

// build a timestamp and measure elapsed time
let start = time.clock.unixMilli()
time.timer.sleep(time.duration.seconds(1))
print(time.timer.since(ts))               // milliseconds since ts
```