# std.time

Time helpers for tool-style scripts.

```tea
use time from "std.time"
```

Examples may be fragments requiring the module import or additional setup.

## std.time.now

```tea
pub def now() -> Timestamp
```

Return the current UTC timestamp.

```tea
use time from "std.time"

const timestamp = time.now()
@println(time.format_rfc3339(timestamp)) # Current UTC time
```

## std.time.now_unix_seconds

```tea
pub def now_unix_seconds() -> Int
```

Return the current Unix timestamp in seconds.

## std.time.now_unix_millis

```tea
pub def now_unix_millis() -> Int
```

Return the current Unix timestamp in milliseconds.

## std.time.sleep

```tea
pub def sleep(delay_ms: Int) -> Void
```

Pause the current thread for the specified number of milliseconds.

## std.time.sleep_for

```tea
pub def sleep_for(duration: Duration) -> Void
```

Pause the current thread for a duration value.

## std.time.from_unix_seconds

```tea
pub def from_unix_seconds(value: Int) -> Timestamp
```

Construct a timestamp from Unix seconds.

## std.time.from_unix_millis

```tea
pub def from_unix_millis(value: Int) -> Timestamp
```

Construct a timestamp from Unix milliseconds.

## std.time.unix_seconds

```tea
pub def unix_seconds(timestamp: Timestamp) -> Int
```

Return the Unix seconds for a timestamp.

## std.time.unix_millis

```tea
pub def unix_millis(timestamp: Timestamp) -> Int
```

Return the Unix milliseconds for a timestamp.

## std.time.milliseconds

```tea
pub def milliseconds(value: Int) -> Duration
```

Create a duration in milliseconds.

## std.time.seconds

```tea
pub def seconds(value: Int) -> Duration
```

Create a duration in seconds.

## std.time.minutes

```tea
pub def minutes(value: Int) -> Duration
```

Create a duration in minutes.

## std.time.hours

```tea
pub def hours(value: Int) -> Duration
```

Create a duration in hours.

## std.time.days

```tea
pub def days(value: Int) -> Duration
```

Create a duration in days.

## std.time.add

```tea
pub def add(left: Duration, right: Duration) -> Duration
```

Return the sum of two durations.

```tea
use time from "std.time"

const delay = time.add(time.seconds(2), time.milliseconds(500))
@println(delay.milliseconds) # 2500
```

## std.time.subtract

```tea
pub def subtract(left: Duration, right: Duration) -> Duration
```

Return the difference between two durations.

## std.time.multiply

```tea
pub def multiply(duration: Duration, factor: Int) -> Duration
```

Multiply a duration by an integer factor.

## std.time.between

```tea
pub def between(start: Timestamp, finish: Timestamp) -> Duration
```

Return the elapsed duration between two timestamps.

```tea
use time from "std.time"

const start = time.from_unix_seconds(10)
const finish = time.from_unix_millis(12500)
@println(time.between(start, finish).milliseconds) # 2500
```

## std.time.add_to

```tea
pub def add_to(timestamp: Timestamp, duration: Duration) -> Timestamp
```

Add a duration to a timestamp.

```tea
use time from "std.time"

const start = time.parse_rfc3339("2026-04-18T12:00:00Z")
const deadline = time.add_to(start, time.minutes(30))
@println(time.format_rfc3339(deadline)) # 2026-04-18T12:30:00Z
```

## std.time.subtract_from

```tea
pub def subtract_from(timestamp: Timestamp, duration: Duration) -> Timestamp
```

Subtract a duration from a timestamp.

## std.time.format_rfc3339

```tea
pub def format_rfc3339(timestamp: Timestamp) -> String
```

Format a timestamp as an RFC3339 string in UTC.

```tea
use time from "std.time"

@println(time.format_rfc3339(time.from_unix_seconds(0))) # 1970-01-01T00:00:00Z
```

## std.time.try_parse_rfc3339

```tea
pub def try_parse_rfc3339(text: String) -> Timestamp ! TimeError
```

Parse an RFC3339 string into a timestamp.

```tea
use time from "std.time"

def demonstrate() -> Void
  var timestamp = try time.try_parse_rfc3339("not-a-date") catch err
    case is time.TimeError.InvalidRfc3339 => time.from_unix_seconds(0)
    case _ => time.from_unix_seconds(0)
  end
  @println(time.format_rfc3339(timestamp)) # 1970-01-01T00:00:00Z
end

demonstrate()
```

## std.time.parse_rfc3339

```tea
pub def parse_rfc3339(text: String) -> Timestamp
```

Parse an RFC3339 string and panic on invalid input.

```tea
use time from "std.time"

const timestamp = time.parse_rfc3339("2026-04-18T14:30:00+02:00")
@println(time.format_rfc3339(timestamp)) # 2026-04-18T12:30:00Z
```

## std.time.to_utc

```tea
pub def to_utc(timestamp: Timestamp) -> DateTime
```

Break a timestamp into UTC calendar components. Weekday is ISO numbering: 1 = Monday through 7 = Sunday.

```tea
use time from "std.time"

const parts = time.to_utc(time.from_unix_seconds(0))
@println(parts.year) # 1970
@println(parts.weekday) # 4 (Thursday; Monday is 1)
```

## std.time.year

```tea
pub def year(timestamp: Timestamp) -> Int
```

Return the UTC year of a timestamp.

## std.time.month

```tea
pub def month(timestamp: Timestamp) -> Int
```

Return the UTC month (1-12) of a timestamp.

## std.time.day

```tea
pub def day(timestamp: Timestamp) -> Int
```

Return the UTC day of month (1-31) of a timestamp.

## std.time.hour

```tea
pub def hour(timestamp: Timestamp) -> Int
```

Return the UTC hour (0-23) of a timestamp.

## std.time.minute

```tea
pub def minute(timestamp: Timestamp) -> Int
```

Return the UTC minute (0-59) of a timestamp.

## std.time.second

```tea
pub def second(timestamp: Timestamp) -> Int
```

Return the UTC second (0-59) of a timestamp.

## std.time.weekday

```tea
pub def weekday(timestamp: Timestamp) -> Int
```

Return the ISO weekday (1 = Monday .. 7 = Sunday) of a timestamp.

## std.time.try_format

```tea
pub def try_format(timestamp: Timestamp, pattern: String) -> String ! TimeError
```

Format a timestamp with a format description such as "[year]-[month]-[day] [hour]:[minute]:[second]".

## std.time.format

```tea
pub def format(timestamp: Timestamp, pattern: String) -> String
```

Format a timestamp with a format description, panicking on failure.

```tea
use time from "std.time"

const timestamp = time.from_calendar(2026, 4, 18, 8, 5, 9)
@println(time.format(timestamp, "[year]-[month]-[day] [hour]:[minute]")) # 2026-04-18 08:05
```

## std.time.try_parse

```tea
pub def try_parse(text: String, pattern: String) -> Timestamp ! TimeError
```

Parse text with a format description into a UTC timestamp. Patterns without an offset are interpreted as UTC.

## std.time.parse

```tea
pub def parse(text: String, pattern: String) -> Timestamp
```

Parse text with a format description, panicking on failure.

```tea
use time from "std.time"

const timestamp = time.parse("2026-04-18", "[year]-[month]-[day]")
@println(time.format_rfc3339(timestamp)) # 2026-04-18T00:00:00Z
```

## std.time.try_from_calendar

```tea
pub def try_from_calendar(in_year: Int, in_month: Int, in_day: Int, in_hour: Int, in_minute: Int, in_second: Int) -> Timestamp ! TimeError
```

Build a UTC timestamp from calendar components.

```tea
use time from "std.time"

def demonstrate() -> Void
  try time.try_from_calendar(2023, 2, 29, 0, 0, 0) catch err
    case is time.TimeError.InvalidDate
      @println("That date does not exist")
      return
    case _
      @panic("unexpected time error")
  end
  return
end

demonstrate()
```

## std.time.from_calendar

```tea
pub def from_calendar(in_year: Int, in_month: Int, in_day: Int, in_hour: Int, in_minute: Int, in_second: Int) -> Timestamp
```

Build a UTC timestamp from calendar components, panicking on failure.

```tea
use time from "std.time"

const timestamp = time.from_calendar(2024, 2, 29, 12, 30, 45)
@println(time.format_date(timestamp)) # 2024-02-29
@println(time.format_time(timestamp)) # 12:30:45
```

## std.time.format_date

```tea
pub def format_date(timestamp: Timestamp) -> String
```

Format a timestamp as "YYYY-MM-DD" in UTC.

```tea
use time from "std.time"

@println(time.format_date(time.from_unix_seconds(0))) # 1970-01-01
```

## std.time.format_time

```tea
pub def format_time(timestamp: Timestamp) -> String
```

Format a timestamp as "HH:MM:SS" in UTC.

```tea
use time from "std.time"

@println(time.format_time(time.from_unix_seconds(0))) # 00:00:00
```