tempo

The main module of this package. Contains most types and only a couple 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

DateOutOfBoundsError

</>

pub type DateOutOfBoundsError {
  DateDayOutOfBounds
  DateMonthOutOfBounds
  DateYearOutOfBounds
}

Constructors

```
DateDayOutOfBounds
```
```
DateMonthOutOfBounds
```
```
DateYearOutOfBounds
```

DateParseError

</>

pub type DateParseError {
  DateInvalidFormat(msg: String)
  DateOutOfBounds(DateOutOfBoundsError)
}

Constructors

```
DateInvalidFormat(msg: String)
```
```
DateOutOfBounds(DateOutOfBoundsError)
```

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 opaque type DateTime

DateTimeOutOfBoundsError

</>

pub type DateTimeOutOfBoundsError {
  DateTimeDateOutOfBounds(DateOutOfBoundsError)
  DateTimeTimeOutOfBounds(TimeOutOfBoundsError)
  DateTimeOffsetOutOfBounds
}

Constructors

DateTimeDateOutOfBounds(DateOutOfBoundsError)

DateTimeTimeOutOfBounds(TimeOutOfBoundsError)

```
DateTimeOffsetOutOfBounds
```

DateTimeParseAnyError

</>

pub type DateTimeParseAnyError {
  DateTimeMissingDate
  DateTimeMissingTime
  DateTimeMissingOffset
}

Constructors

```
DateTimeMissingDate
```
```
DateTimeMissingTime
```
```
DateTimeMissingOffset
```

DateTimeParseError

</>

pub type DateTimeParseError {
  DateTimeInvalidFormat
  DateTimeTimeParseError(TimeParseError)
  DateTimeDateParseError(DateParseError)
  DateTimeOffsetParseError(OffsetParseError)
}

Constructors

```
DateTimeInvalidFormat
```
```
DateTimeTimeParseError(TimeParseError)
```
```
DateTimeDateParseError(DateParseError)
```

DateTimeOffsetParseError(OffsetParseError)

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

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

opaque </>

A datetime value that does not have a timezone 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 opaque type NaiveDateTime

NaiveDateTimeOutOfBoundsError

</>

pub type NaiveDateTimeOutOfBoundsError {
  NaiveDateTimeDateOutOfBounds(DateOutOfBoundsError)
  NaiveDateTimeTimeOutOfBounds(TimeOutOfBoundsError)
}

Constructors

NaiveDateTimeDateOutOfBounds(DateOutOfBoundsError)

NaiveDateTimeTimeOutOfBounds(TimeOutOfBoundsError)

NaiveDateTimeParseAnyError

</>

pub type NaiveDateTimeParseAnyError {
  NaiveDateTimeMissingDate
  NaiveDateTimeMissingTime
}

Constructors

```
NaiveDateTimeMissingDate
```
```
NaiveDateTimeMissingTime
```

NaiveDateTimeParseError

</>

pub type NaiveDateTimeParseError {
  NaiveDateTimeInvalidFormat
  NaiveDateTimeTimeParseError(TimeParseError)
  NaiveDateTimeDateParseError(DateParseError)
}

Constructors

```
NaiveDateTimeInvalidFormat
```

NaiveDateTimeTimeParseError(TimeParseError)

NaiveDateTimeDateParseError(DateParseError)

Offset

opaque </>

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

pub opaque type Offset

OffsetParseError

</>

Error values that can be returned from functions in this package.

pub type OffsetParseError {
  OffsetInvalidFormat(msg: String)
  OffsetOutOfBounds
}

Constructors

```
OffsetInvalidFormat(msg: String)
```
```
OffsetOutOfBounds
```

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 can have different precisions between second and nanosecond, depending on what your application needs.

pub opaque type Time

TimeOutOfBoundsError

</>

pub type TimeOutOfBoundsError {
  TimeHourOutOfBounds
  TimeMinuteOutOfBounds
  TimeSecondOutOfBounds
  TimeNanoSecondOutOfBounds
}

Constructors

```
TimeHourOutOfBounds
```
```
TimeMinuteOutOfBounds
```
```
TimeSecondOutOfBounds
```
```
TimeNanoSecondOutOfBounds
```

TimeParseError

</>

pub type TimeParseError {
  TimeInvalidFormat(msg: String)
  TimeOutOfBounds(TimeOutOfBoundsError)
}

Constructors

```
TimeInvalidFormat(msg: String)
```
```
TimeOutOfBounds(TimeOutOfBoundsError)
```

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 installed 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,
)

UncertainConversion

</>

The result of an uncertain conversion. Since this package does not track timezone offsets, it uses the host system’s offset to convert to local time. If the datetime being converted to local time is of a different day than the current one, the offset value provided by the host may not be accurate (and could be accurate by up to the amount the offset changes throughout the year). To account for this, when converting to local time, a precise value is returned when the datetime being converted is in th current date, while an imprecise value is returned when it is on any other date. This allows the application logic to handle the two cases differently: some applications may only need to convert to local time on the current date or may only need generic time representations, while other applications may need precise conversions for arbitrary dates. More notes on how to plug time zones into this package to aviod uncertain conversions can be found in the README.

pub type UncertainConversion(a) {
  Precise(a)
  Imprecise(a)
}

Constructors

```
Precise(a)
```
```
Imprecise(a)
```

Constants

months

</>

pub const months: List(Month)

An ordered list of all months in the year.

utc

</>

pub const utc: Offset

The Tempo representation of the UTC offset.

Functions

accept_imprecision

</>

pub fn accept_imprecision(conv: UncertainConversion(a)) -> a

Accepts either a precise or imprecise value of an uncertain conversion. Useful for pipelines.

Examples

datetime.literal("2024-06-21T23:17:00Z")
|> datetime.to_local
|> tempo.accept_imprecision
|> datetime.to_string
// -> "2024-06-21T19:17:00-04:00"

error_on_imprecision

</>

pub fn error_on_imprecision(
  conv: UncertainConversion(a),
) -> Result(a, Nil)

Either returns a precise value or an error from an uncertain conversion. Useful for pipelines.

Examples

datetime.literal("2024-06-21T23:17:00Z")
|> datetime.to_local
|> tempo.error_on_imprecision
|> result.try(do_important_precise_task)

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
// )