tempo/date
Functions to use with the Date type in Tempo.
Example
import tempo/date
pub fn main() {
date.literal("2024-06-21")
|> date.to_string
// -> "2024-06-21"
date.parse("06/21/2024", "MM/DD/YYYY")
|> date.to_string
// -> "2024-06-21"
date.now_local()
|> date.to_string
// -> "2024-10-09"
}
import tempo/date
pub fn is_older_than_a_week(date_str: String) {
let date = date.from_string(date_str)
date
|> date.is_earlier(
than: date |> date.subtract(days: 7)
)
}
Types
Functions
pub fn add(date: Date, days days: Int) -> DateAdds a number of days to a date.
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")
pub fn as_period(start start: Date, end end: Date) -> PeriodCreates a period between the first date at 00:00:00 and the second date at 24:00:00. Periods only represent positive datetime differences.
Examples
date.literal("2024-06-12")
|> date.as_period(end: date.literal("2024-06-23"))
|> period.as_days
// -> 11
date.literal("2024-06-12")
|> date.as_period(start: date.literal("2024-06-09"))
|> period.comprising_dates
// -> ["2024-06-09", "2024-06-10", "2024-06-11", "2024-06-12"]
pub fn compare(a: Date, to b: Date) -> OrderCompares two dates.
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
pub fn current_local() -> DateGets the current local date of the host.
Examples
date.current_local()
|> date.to_string
// -> "2024-06-13"
pub fn current_utc() -> DateGets the current UTC date of the host.
Examples
date.current_utc()
|> date.to_string
// -> "2024-06-14"
pub fn day_of_week_to_long_string(
day_of_week: DayOfWeek,
) -> StringReturns the long string representation of a day of the week.
Examples
date|> tempo.date_get_day_of_week_to_long_string(date.Fri)
// -> "Friday"
pub fn day_of_week_to_short_string(
day_of_week: DayOfWeek,
) -> StringReturns the short string representation of a day of the week.
Examples
date|> tempo.date_get_day_of_week_to_short_string(date.Mon)
// -> "Mon"
pub fn difference(from a: Date, to b: Date) -> IntGets the difference between two dates.
Examples
date.literal("2024-06-12")
|> date.difference(from: date.literal("2024-06-23"))
// -> 11
date.literal("2024-06-03")
|> date.difference(from: date.literal("2024-06-11"))
// -> -9
pub fn first_of_month(for date: Date) -> DateGets 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")
pub fn format(date: Date, in fmt: String) -> StringFormats 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"
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: [],
// ),
// ])
pub fn from_string(date: String) -> Result(Date, DateParseError)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)
pub fn from_tuple(
date: #(Int, Int, Int),
) -> Result(Date, DateOutOfBoundsError)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)
pub fn get_day(date: Date) -> IntGets the day value of a date.
Examples
date.literal("2024-06-13")
|> date.get_day
// -> 13
pub fn get_month(date: Date) -> MonthGets the month value of a date.
Examples
date.literal("2024-06-13")
|> date.get_month
// -> tempo.Jun
pub fn get_year(date: Date) -> IntGets the year value of a date.
Examples
date.literal("2024-06-13")
|> date.get_year
// -> 2024
pub fn is_earlier(a: Date, than b: Date) -> BoolChecks 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
pub fn is_earlier_or_equal(a: Date, to b: Date) -> BoolChecks 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
pub fn is_equal(a: Date, to b: Date) -> BoolChecks if two dates are equal.
Example
date.literal("2024-06-12")
|> date.is_equal(to: date.literal("2024-06-12"))
// -> True
pub fn is_later(a: Date, than b: Date) -> BoolChecks 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
pub fn is_later_or_equal(a: Date, to b: Date) -> BoolChecks 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
pub fn is_weekend(date: Date) -> BoolChecks if a date falls in a weekend.
Examples
date.literal("2024-06-22")
|> date.is_weekend
// -> True
pub fn last_of_month(for date: Date) -> DateGets 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")
pub fn literal(date: String) -> DateCreates 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
pub fn new(
year year: Int,
month month: Int,
day day: Int,
) -> Result(Date, DateOutOfBoundsError)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)
pub fn next_day_of_week(
date date: Date,
day_of_week dow: DayOfWeek,
) -> DateGets 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")
pub fn parse(
str: String,
in fmt: String,
) -> Result(Date, DateParseError)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"))
pub fn parse_any(str: String) -> Result(Date, Nil)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"))
pub fn prior_day_of_week(
date date: Date,
day_of_week dow: DayOfWeek,
) -> DateGets 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")
pub fn subtract(date: Date, days days: Int) -> DateSubtracts 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")
pub fn to_day_of_week(date: Date) -> DayOfWeekReturns 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
pub fn to_day_of_week_number(date: Date) -> IntReturns 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
pub fn to_string(date: Date) -> StringReturns 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"