Time

Core

Wall-clock time for the BEAM target. Posix is milliseconds since the Unix epoch.

Zones are Utc, hand-built customZone offsets, or named IANA zones from getZone (common subset, 1970-2038). formatIso always formats as UTC (...Z). format is a strftime-style template over a zone.

This module is selm stdlib for target = "erlang". Browser apps use the client platform Time (utc / here / getZoneName), not Utc / getZone / formatIso. See fixtures/time_dual and examples/17_time_format.

Types

Posix

type Posix = Posix

Instant in time as milliseconds since 1970-01-01T00:00:00Z.

Examples

millisToPosix 0 : Posix

Zone

type Zone = Utc

Time zone: Utc or a customZone offset (minutes from UTC) with optional DST eras.

Examples

toYear Utc (millisToPosix 0) == 1970

Month

type Month
= Jan
| Feb
| Mar
| Apr
| May
| Jun
| Jul
| Aug
| Sep
| Oct
| Nov
| Dec

Calendar month.

Examples

toMonth Utc (millisToPosix 0) == Jan

Weekday

type Weekday
= Mon
| Tue
| Wed
| Thu
| Fri
| Sat
| Sun

Day of the week.

Examples

toWeekday Utc (millisToPosix 0) == Thu

Values

now

now : Transaction Posix

Current UTC time inside a transaction.

Examples

now
-- Transaction Posix

millisToPosix

millisToPosix : Int -> Posix

Convert milliseconds since epoch to Posix.

Examples

millisToPosix 0
-- 1970-01-01T00:00:00.000Z as Posix

posixToMillis

posixToMillis : Posix -> Int

Convert Posix to milliseconds since epoch.

Examples

posixToMillis (millisToPosix 0) == 0

formatIso

formatIso : Posix -> String

Format a Posix instant as an ISO-8601 UTC string (...Z).

Examples

formatIso (millisToPosix 0) == "1970-01-01T00:00:00.000Z"

format

format : String -> Zone -> Posix -> String

Format a Posix instant with a strftime-style template in the given zone.

Supported tokens: %%, %Y, %y, %m, %d, %H, %M, %S, %I, %p, %a, %A, %b, %B, %w, %f, %z. English names only. Unknown %X sequences stay as literals.

Examples

format "%Y-%m-%d" Utc (millisToPosix 0) == "1970-01-01"

customZone

customZone : Int -> List { start : Int , offset : Int } -> Zone

Build a zone from a default UTC offset (minutes) and era exceptions (newest first).

Each era's start is minutes since the Unix epoch; offset is minutes from UTC.

Examples

-- Fixed UTC-5 (e.g. Etc/GMT+5)
customZone (0 - 5 * 60) []

getZone

getZone : String -> Maybe Zone

Look up a named IANA zone (e.g. "America/New_York", "Europe/Tallinn").

Returns Nothing when the name is not in the bundled common-zone subset. Eras live in runtime/selm_tzdata.erl.

Examples

getZone "UTC"
getZone "America/New_York"

ianaVersion

ianaVersion : String

Version string for the bundled IANA snapshot used by getZone.

Examples

ianaVersion == "2024b"

toYear

toYear : Zone -> Posix -> Int

Year in the given zone.

Examples

toYear Utc (millisToPosix 0) == 1970

toMonth

toMonth : Zone -> Posix -> Month

Month in the given zone.

Examples

toMonth Utc (millisToPosix 0) == Jan

toDay

toDay : Zone -> Posix -> Int

Day of month (1-31) in the given zone.

Examples

toDay Utc (millisToPosix 0) == 1

toWeekday

toWeekday : Zone -> Posix -> Weekday

Weekday in the given zone.

Examples

toWeekday Utc (millisToPosix 0) == Thu

toHour

toHour : Zone -> Posix -> Int

Hour of day (0-23) in the given zone.

Examples

toHour Utc (millisToPosix 0) == 0

toMinute

toMinute : Zone -> Posix -> Int

Minute (0-59) in the given zone.

Examples

toMinute Utc (millisToPosix 0) == 0

toSecond

toSecond : Zone -> Posix -> Int

Second (0-59). Zone-independent.

Examples

toSecond Utc (millisToPosix 0) == 0

toMillis

toMillis : Zone -> Posix -> Int

Millisecond (0-999). Zone-independent.

Examples

toMillis Utc (millisToPosix 500) == 500

toOffset

toOffset : Zone -> Posix -> Int

UTC offset in minutes east of UTC for this zone at posix (e.g. -300 for EST).

Examples

toOffset Utc (millisToPosix 0) == 0

every

every : Float -> (Posix -> msg) -> Sub msg

Deliver the current time on an interval, in milliseconds.

Examples

every 1000 Tick
-- Sub Msg