tempo

The main module of this package. Contains most package types and general purpose functions. Look in specific modules for more functionality!

Types

Date

opaque </>

A date value. It represents a specific day on the civil calendar with no time of day associated with it.

pub opaque type Date

DateFormat

</>

Provides common date formatting templates.

The CustomDate format takes a format string that implements the same formatting directives as the nice Day.js library: https://day.js.org/docs/en/display/format.

Values can be escaped by putting brackets around them, like “[Hello!] YYYY”.

pub type DateFormat {
  ISO8601Date
  CustomDate(format: String)
  CustomDateLocalised(format: String, locale: Locale)
}

Constructors

```
ISO8601Date
```
```
CustomDate(format: String)
```

CustomDateLocalised(format: String, locale: Locale)

A datetime value with a timezone offset associated with it. It has the most amount of information about a point in time, and can be compared to all other types in this package by getting its lesser parts.

pub type DateTime {
  DateTime(date: Date, time: Time, offset: Offset)
  LocalDateTime(
    date: Date,
    time: Time,
    offset: Offset,
    tz: TimeZoneProvider,
  )
}

Constructors

DateTime(date: Date, time: Time, offset: Offset)

LocalDateTime(
  date: Date,
  time: Time,
  offset: Offset,
  tz: TimeZoneProvider,
)

DateTimeFormat

</>

Provides common datetime formatting templates.

The Custom format takes a format string that implements the same formatting directives as the nice Day.js library: https://day.js.org/docs/en/display/format, plus condensed offsets.

Values can be escaped by putting brackets around them, like “[Hello!] YYYY”.

Available custom format directives: YY (two-digit year), YYYY (four-digit year), M (month), MM (two-digit month), MMM (short month name), MMMM (full month name), D (day of the month), DD (two-digint day of the month), d (day of the week), dd (min day of the week), ddd (short day of week), dddd (full day of the week), H (hour), HH (two-digit hour), h (12-hour clock hour), hh (two-digit 12-hour clock hour), m (minute), mm (two-digit minute), s (second), ss (two-digit second), SSS (millisecond), SSSS (microsecond), Z (offset from UTC), ZZ (offset from UTC with no “:”), z (short offset from UTC “-04”, “Z”), A (AM/PM), a (am/pm).

pub type DateTimeFormat {
  ISO8601Seconds
  ISO8601Milli
  ISO8601Micro
  HTTP
  Custom(format: String)
  CustomLocalised(format: String, locale: Locale)
  DateFormat(DateFormat)
  TimeFormat(TimeFormat)
}

Constructors

```
ISO8601Seconds
```
```
ISO8601Milli
```
```
ISO8601Micro
```
```
HTTP
```
```
Custom(format: String)
```

CustomLocalised(format: String, locale: Locale)

```
DateFormat(DateFormat)
```
```
TimeFormat(TimeFormat)
```

Duration

opaque </>

A duration between two times. It represents a range of time values and can be span more than a day. It can be used to calculate the number of days, weeks, hours, minutes, or seconds between two times, but cannot accurately be used to calculate the number of years or months between.

It is also used as the basis for specifying how to increase or decrease a datetime or time value.

pub opaque type Duration

Instant

opaque </>

A monotonic type that reperesents a unique point in time on the host system. It can be converted to all other date time types, but cannot be serialized itself. An instant constructed on one host has no meaningful purpose on another host.

pub opaque type Instant

Locale

</>

A type that provides information on how to format dates and times for a specific region or language.

pub type Locale

Month

</>

A specific month on the civil calendar.

pub type Month {
  Jan
  Feb
  Mar
  Apr
  May
  Jun
  Jul
  Aug
  Sep
  Oct
  Nov
  Dec
}

Constructors

```
Jan
```
```
Feb
```
```
Mar
```
```
Apr
```
```
May
```
```
Jun
```
```
Jul
```
```
Aug
```
```
Sep
```
```
Oct
```
```
Nov
```
```
Dec
```

MonthYear

</>

A month in a specific year.

pub type MonthYear {
  MonthYear(month: Month, year: Int)
}

Constructors

```
MonthYear(month: Month, year: Int)
```

NaiveDateTime

</>

A datetime value that does not have a timezone or offset associated with it. It cannot be compared to datetimes with a timezone offset accurately, but can be compared to dates, times, and other naive datetimes.

pub type NaiveDateTime {
  NaiveDateTime(date: Date, time: Time)
}

Constructors

```
NaiveDateTime(date: Date, time: Time)
```

NaiveDateTimeFormat

</>

Provides common naive datetime formatting templates.

The CustomNaive format takes a format string that implements the same formatting directives as the nice Day.js library: https://day.js.org/docs/en/display/format, plus condensed offsets.

Values can be escaped by putting brackets around them, like “[Hello!] YYYY”.

Available custom format directives: YY (two-digit year), YYYY (four-digit year), M (month), MM (two-digit month), MMM (short month name), MMMM (full month name), D (day of the month), DD (two-digint day of the month), d (day of the week), dd (min day of the week), ddd (short day of week), dddd (full day of the week), H (hour), HH (two-digit hour), h (12-hour clock hour), hh (two-digit 12-hour clock hour), m (minute), mm (two-digit minute), s (second), ss (two-digit second), SSS (millisecond), SSSS (microsecond), Z (full offset from UTC in the format “+-00:00”), ZZ (full offset from UTC with no “:”), z (short offset from UTC as “-04” or “Z” if UTC), zz (full offset from UTC as “-04:00” or “Z” if UTC), A (AM/PM), a (am/pm).

pub type NaiveDateTimeFormat {
  NaiveISO8601Seconds
  NaiveISO8601Milli
  NaiveISO8601Micro
  CustomNaive(format: String)
  CustomNaiveLocalised(format: String, locale: Locale)
  NaiveDateFormat(DateFormat)
  NaiveTimeFormat(TimeFormat)
}

Constructors

```
NaiveISO8601Seconds
```
```
NaiveISO8601Milli
```
```
NaiveISO8601Micro
```
```
CustomNaive(format: String)
```

CustomNaiveLocalised(format: String, locale: Locale)

```
NaiveDateFormat(DateFormat)
```
```
NaiveTimeFormat(TimeFormat)
```

Offset

opaque </>

A datetime offset value. It represents the difference between UTC and the datetime value it is associated with.

pub opaque type Offset

Period

opaque </>

A period between two calendar datetimes. It represents a range of datetimes and can be used to calculate the number of days, weeks, months, or years between two dates. It can also be interated over and datetime values can be checked for inclusion in the period.

pub opaque type Period

Time

opaque </>

A time of day value. It represents a specific time on an unspecified date. It cannot be greater than 24 hours or less than 0 hours. It has microsecond precision.

pub opaque type Time

TimeFormat

</>

Provides common time formatting templates.

The CustomTime format takes a format string that implements the same formatting directives as the nice Day.js library: https://day.js.org/docs/en/display/format.

Values can be escaped by putting brackets around them, like “[Hello!] HH”.

Available custom format directives: H (hour), HH (two-digit hour), h (12-hour clock hour), hh (two-digit 12-hour clock hour), m (minute), mm (two-digit minute), s (second), ss (two-digit second), SSS (millisecond), SSSS (microsecond), A (AM/PM), a (am/pm).

pub type TimeFormat {
  ISO8601Time
  ISO8601TimeMilli
  ISO8601TimeMicro
  CustomTime(format: String)
  CustomTimeLocalised(format: String, locale: Locale)
}

Constructors

```
ISO8601Time
```
```
ISO8601TimeMilli
```
```
ISO8601TimeMicro
```
```
CustomTime(format: String)
```

CustomTimeLocalised(format: String, locale: Locale)

TimeZoneProvider

</>

A type for external packages to provide so that datetimes can be converted between timezones. The package gtz was created to provide this and must be added as a project dependency separately.

pub type TimeZoneProvider {
  TimeZoneProvider(
    get_name: fn() -> String,
    calculate_offset: fn(NaiveDateTime) -> Offset,
  )
}

Constructors

TimeZoneProvider(
  get_name: fn() -> String,
  calculate_offset: fn(NaiveDateTime) -> Offset,
)

Functions

compare

</>

pub fn compare(to datetime: DateTime) -> Order

Compares the current system time to the provided datetime value.

Example

tempo.compare(datetime.literal("2024-12-26T00:00:00Z"))
// -> order.Lt

difference

</>

pub fn difference(from start: DateTime) -> Duration

Gets the difference between the current system datetime and the provided datetime.

Example

tempo.difference(from: datetime.literal("2024-10-26T00:00:00Z"))
|> duration.format
// -> "54 days, 13 hours, and 46 minutes"

format_local

</>

pub fn format_local(in format: DateTimeFormat) -> String

Formats the current local system time using the provided format.

Example

tempo.format_local(tempo.ISO8601Seconds)
// -> "2024-12-26T12:32:34-04:00"

format_utc

</>

pub fn format_utc(in format: DateTimeFormat) -> String

Formats the current UTC system time using the provided format.

Example

tempo.format_utc(tempo.ISO8601Seconds)
// -> "2024-12-26T16:32:34Z"

is_earlier

</>

pub fn is_earlier(than datetime: DateTime) -> Bool

Checks if the current system time is earlier than the provided datetime.

Example

tempo.is_earlier(than: datetime.literal("2024-12-26T00:00:00Z"))
// -> False

is_earlier_or_equal

</>

pub fn is_earlier_or_equal(to datetime: DateTime) -> Bool

Checks if the current system time is earlier or equal to the provided datetime.

Example

tempo.is_earlier_or_equal(to: datetime.literal("2024-12-26T00:00:00Z"))
// -> True

is_equal

</>

pub fn is_equal(to datetime: DateTime) -> Bool

Checks if the current system time is equal to the provided datetime.

Example

tempo.is_equal(to: datetime.literal("2024-12-26T00:00:00Z"))
// -> False

is_later

</>

pub fn is_later(than datetime: DateTime) -> Bool

Checks if the current system time is later than the provided datetime.

Example

tempo.is_later(than: datetime.literal("2024-12-26T00:00:00Z"))
// -> True

is_later_or_equal

</>

pub fn is_later_or_equal(to datetime: DateTime) -> Bool

Checks if the current system time is later or equal to the provided datetime.

Example

tempo.is_later_or_equal(to: datetime.literal("2024-12-26T00:00:00Z"))
// -> True

parse_any

</>

pub fn parse_any(
  str: String,
) -> #(Option(Date), Option(Time), Option(Offset))

Tries to parse a given date string without a known format. It will not parse two digit years and will assume the month always comes before the day in a date. Always prefer to use a module’s specific parse function when possible.

Using pattern matching, you can explicitly specify what to with the missing values from the input. Many libaries will assume a missing time value means 00:00:00 or a missing offset means UTC. This design lets the user decide how fallbacks are handled.

Example

case tempo.parse_any("06/21/2024 at 01:42:11 PM") {
  #(Some(date), Some(time), Some(offset)) ->
    datetime.new(date, time, offset)

  #(Some(date), Some(time), None) ->
    datetime.new(date, time, offset.local())

  _ -> datetime.now_local()
}
// -> datetime.literal("2024-06-21T13:42:11-04:00")

tempo.parse_any("2024.06.21 11:32 AM -0400")
// -> #(
//  Some(date.literal("2024-06-21")), 
//  Some(time.literal("11:32:00")),
//  Some(offset.literal("-04:00"))
// )

tempo.parse_any("Dec 25, 2024 at 6:00 AM")
// -> #(
//  Some(date.literal("2024-12-25")), 
//  Some(time.literal("06:00:00")),
//  None
// )

since

</>

pub fn since(start start: DateTime) -> Duration

Gets the time since the provided datetime relative to the current system time. The same as tempo.difference, but a duration of 0 will be returned instead if the datetime is in the future.

Example

tempo.since(datetime.literal("2024-10-26T00:00:00Z"))
|> duration.format
// -> "54 days, 13 hours, and 46 minutes"

tempo.since(datetime.literal("9099-12-26T00:00:00Z"))
|> duration.format
// -> "none"

until

</>

pub fn until(end end: DateTime) -> Duration

Gets the time until the provided datetime relative to the current system time. A duration of 0 will be returned if the datetime in the past.

Example

tempo.until(datetime.literal("2024-10-26T00:00:00Z"))
|> duration.format
// -> "none"

tempo.until(datetime.literal("2025-02-26T00:00:00Z"))
|> duration.format
// -> "54 days, 13 hours, and 46 minutes"