tempo/date · gtempo

Examples

date.literal("2024-06-12")
|> date.add(days: 1)
// -> date.literal("2024-06-13")

date.literal("2024-06-12")
|> date.add(days: 12)
// -> date.literal("2024-06-24")

as_period

</>

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

Creates a period between the first date at 00:00:00 and the second date at 24:00:00.

Examples

date.literal("2024-06-12")
|> date.difference(from: date.literal("2024-06-23"))
|> period.as_days
// -> 11

date.literal("2024-06-12")
|> date.difference(from: date.literal("2024-06-03"))
|> period.as_days
// -> 9

Examples

date.literal("2024-06-12")
|> date.compare(to: date.literal("2024-06-12"))
// -> order.Eq

date.literal("2024-05-12")
|> date.compare(to: date.literal("2024-06-13"))
// -> order.Lt

date.literal("2034-06-12")
|> date.compare(to: date.literal("2024-06-11"))
// -> order.Gt

Examples

date.current_local()
|> date.to_string
// -> "2024-06-13"

Examples

date.current_utc()
|> date.to_string
// -> "2024-06-14"

day_of_week_to_long_string

</>

pub fn day_of_week_to_long_string(
  day_of_week: DayOfWeek,
) -> String

Returns the long string representation of a day of the week.

Examples

date.day_of_week_to_long_string(date.Fri)
// -> "Friday"

day_of_week_to_short_string

</>

pub fn day_of_week_to_short_string(
  day_of_week: DayOfWeek,
) -> String

Returns the short string representation of a day of the week.

Examples

date.day_of_week_to_short_string(date.Mon)
// -> "Mon"

difference

</>

pub fn difference(of a: Date, from b: Date) -> Period

Gets the difference between two dates as a period between the two dates at 00:00:00 each.

Examples

date.literal("2024-06-12")
|> date.difference(from: date.literal("2024-06-23"))
|> period.as_days
// -> 11

date.literal("2024-06-12")
|> date.difference(from: date.literal("2024-06-03"))
|> period.as_days
// -> 9

first_of_month

</>

pub fn first_of_month(for date: Date) -> Date

Gets the first date of the month a date occurs in.

Examples

date.literal("2024-06-21")
|> date.first_of_month
// -> date.literal("2024-06-01")

format

</>

pub fn format(date: Date, 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(Date, List(DecodeError))

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

Examples

dynamic.from("2024-06-21")
|> date.from_dynamic_string
// -> Ok(date.literal("2024-06-21"))

dynamic.from("153")
|> datetime.from_dynamic_string
// -> Error([
//   dynamic.DecodeError(
//     expected: "tempo.Date",
//     found: "Invalid format: 153",
//     path: [],
//   ),
// ])

from_string

</>

pub fn from_string(date: String) -> Result(Date, Error)

Parses a date string in the format 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

date.from_string("2024-06-13")
// -> Ok(date.literal("2024-06-13"))

date.from_string("20240613")
// -> Ok(date.literal("2024-06-13"))

date.from_string("2409")
// -> Error(tempo.DateInvalidFormat)

from_tuple

</>

pub fn from_tuple(date: #(Int, Int, Int)) -> Result(Date, Error)

Returns a date value from a tuple of ints if the values represent the years, month, and day of a valid date. The year must be greater than 1000.

Years less than 1000 are technically valid years, but are not common and usually indicate that either a non-year value was passed as the year or a two digit year was passed (which are too abiguous to be confidently accepted).

Examples

date.from_tuple(#(2024, 6, 13))
// -> Ok(date.literal("2024-06-13"))

date.from_tuple(#(98, 6, 13))
// -> Error(tempo.DateOutOfBounds)

get_day

</>

pub fn get_day(date: Date) -> Int

Gets the day value of a date.

Examples

date.literal("2024-06-13")
|> date.get_day
// -> 13

get_month

</>

pub fn get_month(date: Date) -> Month

Gets the month value of a date.

Examples

date.literal("2024-06-13")
|> date.get_month
// -> tempo.Jun

get_year

</>

pub fn get_year(date: Date) -> Int

Gets the year value of a date.

Examples

date.literal("2024-06-13")
|> date.get_year
// -> 2024

is_earlier

</>

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

Checks of the first date is earlier than the second date.

Examples

date.literal("2024-06-12")
|> date.is_earlier(than: date.literal("2024-06-13"))
// -> True

date.literal("2024-06-12")
|> date.is_earlier(than: date.literal("2024-06-12"))
// -> False

is_earlier_or_equal

</>

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

Checks if the first date is earlier than or equal to the second date.

Examples

date.literal("2024-06-12")
|> date.is_earlier_or_equal(to: date.literal("2024-06-12"))
// -> True

date.literal("2024-06-12")
|> date.is_earlier_or_equal(to: date.literal("2024-06-11"))
// -> False

is_equal

</>

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

Checks if two dates are equal.

Example

date.literal("2024-06-12")
|> date.is_equal(to: date.literal("2024-06-12"))
// -> True

is_later

</>

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

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

Examples

date.literal("2024-06-14")
|> date.is_later(than: date.literal("2024-06-13"))
// -> True

date.literal("2024-06-12")
|> date.is_later(than: date.literal("2024-06-12"))
// -> False

is_later_or_equal

</>

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

Checks if the first date is later than or equal to the second date.

Examples

date.literal("2024-06-12")
|> date.is_later_or_equal(to: date.literal("2024-06-12"))
// -> True

date.literal("2024-06-12")
|> date.is_later_or_equal(to: date.literal("2024-06-13"))
// -> False

is_weekend

</>

pub fn is_weekend(date: Date) -> Bool

Checks if a date falls in a weekend.

Examples

date.literal("2024-06-22")
|> date.is_weekend
// -> True

last_of_month

</>

pub fn last_of_month(for date: Date) -> Date

Gets the last date of the month a date occurs in.

Examples

date.literal("2024-02-13")
|> date.last_of_month
// -> date.literal("2024-02-29")

literal

</>

pub fn literal(date: String) -> Date

Creates a new date value from a string literal, but will panic if the string is invalid. Accepted formats are 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.

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

Examples

date.literal("2024-06-13")
|> date.to_string
// -> "2024-06-13"

date.literal("20240613")
|> date.to_string
// -> "2024-06-13"

date.literal("2409")
// -> panic

new

</>

pub fn new(
  year year: Int,
  month month: Int,
  day day: Int,
) -> Result(Date, Error)

Creates a new date and validates it.

Examples

date.new(2024, 6, 13)
// -> Ok(date.literal("2024-06-13"))

date.new(2024, 6, 31)
// -> Error(tempo.DateOutOfBounds)

next_day_of_week

</>

pub fn next_day_of_week(
  date date: Date,
  day_of_week dow: DayOfWeek,
) -> Date

Gets the date of the next specified day of the week, exclusive of the passed date.

Examples

date.literal("2024-06-21")
|> date.next_day_of_week(date.Mon)
// -> date.literal("2024-06-24")

date.literal("2024-06-21")
|> date.next_day_of_week(date.Fri)
// -> date.literal("2024-06-28")

parse

</>

pub fn parse(str: String, in fmt: String) -> Result(Date, Error)

Parses a date string in the provided format. Always prefer using this over parse_any. All parsed formats must have all parts of a date.

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

Example

date.parse("2024/06/08, 13:42:11", "YYYY/MM/DD")
// -> Ok(date.literal("2024-06-08"))

date.parse("January 13, 2024", "MMMM DD, YYYY")
// -> Ok(date.literal("2024-01-13"))

date.parse("Hi! 2024 11 13", "[Hi!] YYYY M D")
// -> Ok(date.literal("2024-11-13"))

parse_any

</>

pub fn parse_any(str: String) -> Result(Date, Error)

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. Will leave off any time offset values present.

Example

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

date.parse_any("2024.06.21")
// -> Ok(date.literal("2024-06-21"))

prior_day_of_week

</>

pub fn prior_day_of_week(
  date date: Date,
  day_of_week dow: DayOfWeek,
) -> Date

Gets the date of the prior specified day of the week, exclusive of the passed date.

Examples

date.literal("2024-06-21")
|> date.prior_day_of_week(date.Mon)
// -> date.literal("2024-06-17")

date.literal("2024-06-21")
|> date.prior_day_of_week(date.Fri)
// -> date.literal("2024-06-14")

subtract

</>

pub fn subtract(date: Date, days days: Int) -> Date

Subtracts a number of days from a date.

Examples

date.literal("2024-06-12")
|> date.subtract(days: 1)
// -> date.literal("2024-06-11")

date.literal("2024-06-12")
|> date.subtract(days: 12)
// -> date.literal("2024-05-31")

to_day_of_week

</>

pub fn to_day_of_week(date: Date) -> DayOfWeek

Returns the day of week a date falls on. Will be incorrect for dates before 1752 and dates after 2300.

Examples

date.literal("2024-06-20")
|> date.to_day_of_week
// -> Thur

to_day_of_week_number

</>

pub fn to_day_of_week_number(date: Date) -> Int

Returns the number of the day of week a date falls on. Will be incorrect for dates before 1752 and dates after 2300.

Examples

date.literal("2024-06-21")
|> date.to_day_of_week_number
// -> 5

to_string

</>

pub fn to_string(date: Date) -> String

Returns a string representation of a date value in the format YYYY-MM-DD.

Examples

date.literal("2024-06-13")
|> date.to_string
// -> "2024-06-13"

to_tuple

</>

pub fn to_tuple(date: Date) -> #(Int, Int, Int)

Returns a tuple of ints from a date value that represent the year, month, and day of the date.

Examples

date.literal("2024-06-14")
|> date.to_tuple
// -> #(2024, 6, 14)

to_weekday

</>

pub fn to_weekday(date: Date) -> DayOfWeek

Deprecated: Use `to_day_of_week` instead

Constructors

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Example

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Example

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Example

Example

Examples

Examples

Examples

Examples

Examples

Examples