tempo/datetime · gtempo

Examples

datetime.literal("2024-06-12T23:17:00Z")
|> datetime.add(duration |> tempo.offset_get_minutes(3))
// -> datetime.literal("2024-06-12T23:20:00Z")

apply_offset

</>

pub fn apply_offset(datetime: DateTime) -> NaiveDateTime

Applies the offset of a datetime to the date and time values, resulting in a new naive datetime value that represents the original datetime in UTC time.

Examples

datetime.literal("2024-06-21T05:36:11.195-04:00")
|> datetime.apply_offset
// -> naive_datetime.literal("2024-06-21T09:36:11.195")

as_period

</>

pub fn as_period(
  start start: DateTime,
  end end: DateTime,
) -> Period

Creates a period between two datetimes, where the start and end times are the equivalent UTC times of the provided datetimes. The specified start and end datetimes will be swapped if the start datetime is later than the end datetime.

Examples

datetime.to_period(
  start: datetime.literal("2024-06-12T23:17:00Z")
  end: datetime.literal("2024-06-16T01:16:12Z"),
)
|> period.as_days
// -> 3

datetime.to_period(
  start: datetime.literal("2024-06-12T23:17:00Z")
  end: datetime.literal("2024-06-16T01:18:12Z"),
)
|> period.format
// -> "3 days, 2 hours, and 1 minute"

compare

</>

pub fn compare(a: DateTime, to b: DateTime) -> Order

Compares two datetimes.

Examples

datetime.literal("2024-06-21T23:47:00+09:05")
|> datetime.compare(to: datetime.literal("2024-06-21T23:47:00+09:05"))
// -> order.Eq

datetime.literal("2023-05-11T13:30:00-04:00")
|> datetime.compare(to: datetime.literal("2023-05-11T13:15:00Z"))
// -> order.Lt

datetime.literal("2024-06-12T23:47:00+09:05")
|> datetime.compare(to: datetime.literal("2022-04-12T00:00:00"))
// -> order.Gt

difference

</>

pub fn difference(from a: DateTime, to b: DateTime) -> Duration

Returns the difference between two datetimes as a duration between their equivalent UTC times.

Examples

datetime.literal("2024-06-12T23:17:00Z")
|> datetime.difference(
  from: datetime.literal("2024-06-16T01:16:12Z"),
)
|> duration.as_days
// -> 3

datetime.literal("2024-06-12T23:17:00Z")
|> datetime.difference(
  from: datetime.literal("2024-06-16T01:18:12Z"),
)
|> duration.format
// -> "3 days, 2 hours, and 1 minute"

drop_offset

</>

pub fn drop_offset(datetime: DateTime) -> NaiveDateTime

Drops the time of a datetime, leaving the date and time values unchanged.

Examples

datetime.literal("2024-06-13T13:42:11.195Z")
|> datetime.drop_offset
// -> naive_datetime.literal("2024-06-13T13:42:11")

drop_time

</>

pub fn drop_time(datetime: DateTime) -> DateTime

Drops the time of a datetime, leaving the date value unchanged.

Examples

datetime.literal("2024-06-18T13:42:11.195Z")
|> datetime.drop_time
// -> naive_datetime.literal("2024-06-18T00:00:00Z")

format

</>

pub fn format(datetime: DateTime, in fmt: String) -> String

Formats a datetime value into a string using the provided format string. Implements the same formatting directives as the great Day.js library: https://day.js.org/docs/en/display/format, plus short timezones and nanosecond precision.

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

Available 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-digit 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), SSSSS (nanosecond), Z (offset from UTC), ZZ (offset from UTC with no “:”), z (short offset from UTC “-04”, “Z”), A (AM/PM), a (am/pm).

Example

datetime.literal("2024-06-21T13:42:11.314-04:00")
|> datetime.format("ddd @ h:mm A (z)")
// -> "Fri @ 1:42 PM (-04)"

datetime.literal("2024-06-03T09:02:01-04:00")
|> datetime.format("YY YYYY M MM MMM MMMM D DD d dd ddd")
// --------------> "24 2024 6 06 Jun June 3 03 1 Mo Mon"

datetime.literal("2024-06-03T09:02:01.014920202-00:00")
|> datetime.format("dddd SSS SSSS SSSSS Z ZZ z")
// -> "Monday 014 014920 014920202 -00:00 -0000 Z"

datetime.literal("2024-06-03T13:02:01-04:00")
|> datetime.format("H HH h hh m mm s ss a A [An ant]")
// -------------> "13 13 1 01 2 02 1 01 pm PM An ant"

from_dynamic_string

</>

pub fn from_dynamic_string(
  dynamic_string: Dynamic,
) -> Result(DateTime, List(DecodeError))

Checks if a dynamic value is a valid datetime string, and returns the datetime if it is.

Examples

dynamic.from("2024-06-13T13:42:11.195Z")
|> datetime.from_dynamic_string
// -> Ok(datetime.literal("2024-06-13T13:42:11.195Z"))

dynamic.from("24-06-13,13:42:11.195")
|> datetime.from_dynamic_string
// -> Error([
//   dynamic.DecodeError(
//     expected: "tempo.DateTime",
//     found: "Invalid format: 24-06-13,13:42:11.195",
//     path: [],
//   ),
// ])

from_dynamic_unix_micro_utc

</>

pub fn from_dynamic_unix_micro_utc(
  dynamic_ts: Dynamic,
) -> Result(DateTime, List(DecodeError))

Checks if a dynamic value is a valid unix timestamp in microseconds, and returns the datetime if it is.

Examples

dynamic.from(1_718_629_314_334_734)
|> datetime.from_dynamic_unix_utc
// -> Ok(datetime.literal("2024-06-17T13:01:54.334734Z"))

dynamic.from("hello")
|> datetime.from_dynamic_unix_utc
// -> Error([
//   dynamic.DecodeError(
//     expected: "Int",
//     found: "String",
//     path: [],
//   ),
// ])

from_dynamic_unix_milli_utc

</>

pub fn from_dynamic_unix_milli_utc(
  dynamic_ts: Dynamic,
) -> Result(DateTime, List(DecodeError))

Checks if a dynamic value is a valid unix timestamp in milliseconds, and returns the datetime if it is.

Examples

dynamic.from(1_718_629_314_334)
|> datetime.from_dynamic_unix_utc
// -> Ok(datetime.literal("2024-06-17T13:01:54.334Z"))

dynamic.from("hello")
|> datetime.from_dynamic_unix_utc
// -> Error([
//   dynamic.DecodeError(
//     expected: "Int",
//     found: "String",
//     path: [],
//   ),
// ])

from_dynamic_unix_utc

</>

pub fn from_dynamic_unix_utc(
  dynamic_ts: Dynamic,
) -> Result(DateTime, List(DecodeError))

Checks if a dynamic value is a valid unix timestamp in seconds, and returns the datetime if it is.

Examples

dynamic.from(1_718_629_314)
|> datetime.from_dynamic_unix_utc
// -> Ok(datetime.literal("2024-06-17T13:01:54Z"))

dynamic.from("hello")
|> datetime.from_dynamic_unix_utc
// -> Error([
//   dynamic.DecodeError(
//     expected: "Int",
//     found: "String",
//     path: [],
//   ),
// ])

from_string

</>

pub fn from_string(
  datetime: String,
) -> Result(DateTime, DateTimeParseError)

Parses a datetime string in the format YYYY-MM-DDThh:mm:ss.sTZD, YYYYMMDDThhmmss.sTZD, YYYY-MM-DD hh:mm:ss.sTZD, YYYYMMDD hhmmss.sTZD, YYYY-MM-DD, YYYY-M-D, YYYY/MM/DD, YYYY/M/D, YYYY.MM.DD, YYYY.M.D, YYYY_MM_DD, YYYY_M_D, YYYY MM DD, YYYY M D, or YYYYMMDD.

Examples

datetime.from_string("20240613T230400.009+00:00")
// -> datetime.literal("2024-06-13T23:04:00.009Z")

from_unix_micro_utc

</>

pub fn from_unix_micro_utc(unix_ts: Int) -> DateTime

Returns the UTC datetime of a unix timestamp in microseconds.

Examples

datetime.from_unix_micro_utc(1_718_629_314_334_734)
// -> datetime.literal("2024-06-17T13:01:54.334734Z")

from_unix_milli_utc

</>

pub fn from_unix_milli_utc(unix_ts: Int) -> DateTime

Returns the UTC datetime of a unix timestamp in milliseconds.

Examples

datetime.from_unix_milli_utc(1_718_629_314_334)
// -> datetime.literal("2024-06-17T13:01:54.334Z")

from_unix_utc

</>

pub fn from_unix_utc(unix_ts: Int) -> DateTime

Returns the UTC datetime of a unix timestamp.

Examples

datetime.from_unix_utc(1_718_829_191)
// -> datetime.literal("2024-06-17T12:59:51Z")

get_date

</>

pub fn get_date(datetime: DateTime) -> Date

Gets the date of a datetime.

Examples

datetime.literal("2024-06-21T13:42:11.195Z")
|> datetime.get_date
// -> date.literal("2024-06-21")

get_offset

</>

pub fn get_offset(datetime: DateTime) -> Offset

Gets the offset of a datetime.

Examples

datetime.literal("2024-06-12T13:42:11.195-04:00")
|> datetime.get_offset
// -> offset.literal("+04:00")

get_time

</>

pub fn get_time(datetime: DateTime) -> Time

Gets the time of a datetime.

Examples

datetime.literal("2024-06-21T13:42:11.195Z")
|> datetime.get_time
// -> time.literal("13:42:11.195")

get_timezone_name

</>

pub fn get_timezone_name(datetime: DateTime) -> Option(String)

Gets the name of the timezone the datetime is in.

Example

datetime.literal("2024-06-21T06:30:02.334Z")
|> datetime.get_timezone_name
// -> None

import gtz
let assert Ok(tz) = gtz.timezone("Europe/London")
datetime.now_local()
|> datetime.to_timezone(tz)
|> datetime.get_timezone_name
// -> Some("Europe/London")

is_earlier

</>

pub fn is_earlier(a: DateTime, than b: DateTime) -> Bool

Checks if the first datetime is earlier than the second datetime.

Examples

datetime.literal("2024-06-21T23:47:00+09:05")
|> datetime.is_earlier(
  than: datetime.literal("2024-06-21T23:47:00+09:05"),
)
// -> False

datetime.literal("2023-05-11T13:30:00-04:00")
|> datetime.is_earlier(
  than: datetime.literal("2023-05-11T13:15:00Z"),
)
// -> True

is_earlier_or_equal

</>

pub fn is_earlier_or_equal(a: DateTime, to b: DateTime) -> Bool

Checks if the first datetime is earlier or equal to the second datetime.

Examples

datetime.literal("2024-06-21T23:47:00+09:05")
|> datetime.is_earlier_or_equal(
  to: datetime.literal("2024-06-21T23:47:00+09:05"),
)
// -> True

datetime.literal("2024-07-15T23:40:00-04:00")
|> datetime.is_earlier_or_equal(
  to: datetime.literal("2023-05-11T13:15:00Z"),
)
// -> False

is_equal

</>

pub fn is_equal(a: DateTime, to b: DateTime) -> Bool

Checks if the first datetime is equal to the second datetime.

Examples

datetime.literal("2024-06-21T09:44:00Z")
|> datetime.is_equal(
  to: datetime.literal("2024-06-21T05:44:00-04:00"),
)
// -> True

datetime.literal("2024-06-21T09:44:00Z")
|> datetime.is_equal(
  to: datetime.literal("2024-06-21T09:44:00.045Z"),
)
// -> False

is_later

</>

pub fn is_later(a: DateTime, than b: DateTime) -> Bool

Checks if the first datetime is later than the second datetime.

Examples

datetime.literal("2024-06-21T23:47:00+09:05")
|> datetime.is_later(
  than: datetime.literal("2024-06-21T23:47:00+09:05"),
)
// -> False

datetime.literal("2023-05-11T13:00:00+04:00")
|> datetime.is_later(
  than: datetime.literal("2023-05-11T13:15:00.534Z"),
)
// -> True

is_later_or_equal

</>

pub fn is_later_or_equal(a: DateTime, to b: DateTime) -> Bool

Checks if the first datetime is later or equal to the second datetime.

Examples

datetime.literal("2016-01-11T03:47:00+09:05")
|> datetime.is_later_or_equal(
  to: datetime.literal("2024-06-21T23:47:00+09:05"),
)
// -> False

datetime.literal("2024-07-15T23:40:00-04:00")
|> datetime.is_later_or_equal(
  to: datetime.literal("2023-05-11T13:15:00Z"),
)
// -> True

literal

</>

pub fn literal(datetime: String) -> DateTime

Create a new datetime value from a string literal, but will panic if the string is invalid. Accepted formats are YYYY-MM-DDThh:mm:ss.sTZD or YYYYMMDDThhmmss.sTZD

Useful for declaring datetime literals that you know are valid within your
program.

Examples

datetime.literal("2024-06-13T23:04:00.009+10:00")
|> datetime.to_string
// -> "2024-06-13T23:04:00.009+10:00"

new

</>

pub fn new(
  date date: Date,
  time time: Time,
  offset offset: Offset,
) -> DateTime

Create a new datetime from a date, time, and offset.

Examples

datetime.new(
  date.literal("2024-06-13"), 
  time.literal("23:04:00.009"),
  offset.literal("+10:00"),
)
// -> datetime.literal("2024-06-13T23:04:00.009+10:00")

now_local

</>

pub fn now_local() -> DateTime

Gets the current local datetime of the host. Always prefer using duration.start_monotonic to record time passing and time.now_unique to sort events by time.

Examples

datetime.now()
|> datetime.to_string
// -> "2024-06-14T04:19:20.006809349-04:00"

now_utc

</>

pub fn now_utc() -> DateTime

Gets the current UTC datetime of the host.Always prefer using duration.start_monotonic to record time passing and time.now_unique to sort events by time.

Examples

datetime.now_utc()
|> datetime.to_string
// -> "2024-06-14T08:19:20.006809349Z"

parse

</>

pub fn parse(
  str: String,
  in fmt: String,
) -> Result(DateTime, DateTimeParseError)

Parses a datetime string in the provided format. Always prefer using this over parse_any. All parsed formats must have all parts of a datetime (date, time, offset). Use the other modules for parsing lesser date time values.

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

Available 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-digit day of the month), 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), SSSSS (nanosecond), Z (offset from UTC), ZZ (offset from UTC with no “:”), z (short offset from UTC “-04”, “Z”), A (AM/PM), a (am/pm).

Example

datetime.parse("2024/06/08, 13:42:11, -04:00", "YYYY/MM/DD, HH:mm:ss, Z")
// -> Ok(datetime.literal("2024-06-08T13:42:11-04"))

datetime.parse("January 13, 2024. 3:42:11Z", "MMMM DD, YYYY. H:mm:ssz")
// -> Ok(datetime.literal("2024-01-13T03:42:11Z"))

datetime.parse("Hi! 2024 11 13 12 2 am Z", "[Hi!] YYYY M D h m a z")
// -> Ok(datetime.literal("2024-11-13T00:02:00Z"))

parse_any

</>

pub fn parse_any(
  str: String,
) -> Result(DateTime, DateTimeParseAnyError)

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.

Example

parse_any.parse_any("2024.06.21 01:32 PM -0400")
// -> Ok(datetime.literal("2024-06-21T13:32:00-04:00"))

parse_any.parse_any("2024.06.21 01:32 PM")
// -> Error(tempo.ParseMissingOffset)

subtract

</>

pub fn subtract(
  datetime: DateTime,
  duration duration_to_subtract: Duration,
) -> DateTime

Subtracts a duration from a datetime.

Examples

datetime.literal("2024-06-21T23:17:00Z")
|> datetime.subtract(duration.days(3))
// -> datetime.literal("2024-06-18T23:17:00Z")

time_left_in_day

</>

pub fn time_left_in_day(datetime: DateTime) -> Time

Gets the time left in the day.

Does not account for leap seconds like the rest of the package.

Examples

naive_datetime.literal("2015-06-30T23:59:03Z")
|> naive_datetime.time_left_in_day
// -> time.literal("00:00:57")

naive_datetime.literal("2024-06-18T08:05:20-04:00")
|> naive_datetime.time_left_in_day
// -> time.literal("15:54:40")

to_local

</>

pub fn to_local(
  datetime: DateTime,
) -> UncertainConversion(DateTime)

Converts a datetime to the equivalent local datetime. The return value indicates if the conversion was precise or imprecise. Use pattern matching or the tempo.accept_imprecision function to handle the two cases.

Conversion is based on the host’s current offset. If the date of the supplied datetime matches the date of the host, then we can apply the current host’s offset to get the local time safely, resulting in a precise conversion. If the date does not match the host’s, then we can not be sure the current offset is still applicable, and will perform an imprecise conversion. The imprecise conversion can be inaccurate to the degree the local offset changes throughout the year. For example, in North America where Daylight Savings Time is observed with a one-hour time shift, the imprecise conversion can be off by up to an hour depending on the time of year.

Examples

datetime.literal("2024-06-21T09:57:11.195Z")
|> datetime.to_local
// -> tempo.Precise(datetime.literal("2024-06-21T05:57:11.195-04:00"))

datetime.literal("1998-08-23T09:57:11.195Z")
|> datetime.to_local
// -> tempo.Imprecise(datetime.literal("1998-08-23T05:57:11.195-04:00"))

to_local_date

</>

pub fn to_local_date(
  datetime: DateTime,
) -> UncertainConversion(Date)

Converts a datetime to the equivalent local time. The return value indicates if the conversion was precise or imprecise. Use pattern matching or the tempo.accept_imprecision function to handle the two cases.

Conversion is based on the host’s current offset. If the date of the supplied datetime matches the date of the host, then we can apply the current host’s offset to get the local time safely, resulting in a precise conversion. If the date does not match the host’s, then we can not be sure the current offset is still applicable, and will perform an imprecise conversion. The imprecise conversion can be inaccurate to the degree the local offset changes throughout the year. For example, in North America where Daylight Savings Time is observed with a one-hour time shift, the imprecise conversion can be off by up to an hour depending on the time of year.

Examples

datetime.literal("2024-06-19T01:35:11.195Z")
|> datetime.to_local_date
// -> tempo.Precise(date.literal("2024-06-18"))

datetime.literal("1998-08-23T01:57:11.195Z")
|> datetime.to_local_date
// -> tempo.Imprecise(date.literal("1998-08-22"))

to_local_time

</>

pub fn to_local_time(
  datetime: DateTime,
) -> UncertainConversion(Time)

Converts a datetime to the equivalent local time. The return value indicates if the conversion was precise or imprecise. Use pattern matching or the tempo.accept_imprecision function to handle the two cases.

Conversion is based on the host’s current offset. If the date of the supplied datetime matches the date of the host, then we can apply the current host’s offset to get the local time safely, resulting in a precise conversion. If the date does not match the host’s, then we can not be sure the current offset is still applicable, and will perform an imprecise conversion. The imprecise conversion can be inaccurate to the degree the local offset changes throughout the year. For example, in North America where Daylight Savings Time is observed with a one-hour time shift, the imprecise conversion can be off by up to an hour depending on the time of year.

Examples

datetime.literal("2024-06-21T09:57:11.195Z")
|> datetime.to_local_time
// -> tempo.Precise(time.literal("05:57:11.195"))

datetime.literal("1998-08-23T09:57:11.195Z")
|> datetime.to_local_time
// -> tempo.Imprecise(time.literal("05:57:11.195"))

to_offset

</>

pub fn to_offset(datetime: DateTime, offset: Offset) -> DateTime

Converts a datetime to the equivalent time in an offset.

Examples

datetime.literal("2024-06-21T05:36:11.195-04:00")
|> datetime.to_offset(offset.literal("+10:00"))
// -> datetime.literal("2024-06-21T19:36:11.195+10:00")

to_string

</>

pub fn to_string(datetime: DateTime) -> String

Returns a string representation of a datetime value in the ISO 8601 format.

Examples

datetime.now_utc()
|> datetime.to_string
// -> "2024-06-21T05:22:22.009Z"

to_timezone

</>

pub fn to_timezone(
  datetime: DateTime,
  tz: TimeZoneProvider,
) -> DateTime

Converts a datetime to the specified timezone. Relies on an external package like gtz to provide timezone information. Try to prefer using to_local when converting datetimes to local time, as that does not depend on any external package.

Example

import gtz
let assert Ok(tz) = gtz.timezone("America/New_York")
datetime.literal("2024-06-21T06:30:02.334Z")
|> datetime.to_timezone(tz)
|> datetime.to_string
// -> "2024-01-03T02:30:02.334-04:00"

import gtz
let assert Ok(local_tz) = gtz.local_name() |> gtz.timezone
datetime.from_unix_utc(1_729_257_776)
|> datetime.to_timezone(local_tz)
|> datetime.to_string
// -> "2024-10-18T14:22:56.000+01:00"

to_unix_micro_utc

</>

pub fn to_unix_micro_utc(datetime: DateTime) -> Int

Returns the UTC unix timestamp in microseconds of a datetime.

Examples

datetime.literal("2024-06-17T13:01:54.334734Z")
|> datetime.to_unix_micro_utc
// -> 1_718_629_314_334_734

to_unix_milli_utc

</>

pub fn to_unix_milli_utc(datetime: DateTime) -> Int

Returns the UTC unix timestamp in milliseconds of a datetime.

Examples

datetime.literal("2024-06-17T13:01:54.334Z")
|> datetime.to_unix_milli_utc
// -> 1_718_629_314_334

to_unix_utc

</>

pub fn to_unix_utc(datetime: DateTime) -> Int

Returns the UTC unix timestamp of a datetime.

Examples

datetime.literal("2024-06-17T12:59:51Z")
|> datetime.to_unix_utc
// -> 1_718_829_191

to_utc

</>

pub fn to_utc(datetime: DateTime) -> DateTime

Converts a datetime to the equivalent UTC time.

Examples

datetime.literal("2024-06-21T05:36:11.195-04:00")
|> datetime.to_utc
// -> datetime.literal("2024-06-21T09:36:11.195Z")