Skip to content

Date

As there is no native datetime datatype in the DSL, all date functions expect a valid ISO date string as input, and also return an ISO date string. Internally, the Timex library is used for all date operations.

date_ceil(datetime, arg2)

Rounds the given datetime up to the nearest multiple of the given minutes.

:minutes can only be a number from 0..60.

Examples:

iex> date_ceil("2024-01-01T09:00:00Z", minutes: 15)
"2024-01-01T09:00:00+00:00"
iex> date_ceil("2024-01-01T09:03:14Z", minutes: 15)
"2024-01-01T09:15:00+00:00"
iex> date_ceil("2024-01-01T09:15:01Z", minutes: 15)
"2024-01-01T09:30:00+00:00"
iex> date_ceil("2024-01-01T09:55:01Z", minutes: 15)
"2024-01-01T10:00:00+00:00"

date_compare(left, right)

Compares two datetimes.

Returns :lt when the first datetime is before the second, :gt for vice versa, and :eq if they are the same. If either of the given dates is invalid, it returns :invalid_date instead.

Note that both UTC and Standard offsets will be taken into account when comparison is done.

date_diff(a, b, granularity)

Get the difference between two dates.

You need to specify a diff granularity, any of the following:

  • :years
  • :months
  • :calendar_weeks (weeks of the calendar as opposed to actual weeks in terms of days)
  • :weeks
  • :days
  • :hours
  • :minutes
  • :seconds
  • :milliseconds
  • :microseconds
  • :duration

and the result will be an integer value of those units or a Duration struct. The diff value will be negative if a comes before b, and positive if a comes after b. This behaviour mirrors compare/3.

See the Timex manual.

Examples:

iex> date_diff("2020-06-10T00:00:00+00:00", "2021-06-10T00:00:00+00:00", :years)
-1
iex> date_diff("2020-06-10T00:00:00+00:00", "2020-08-10T00:00:00+00:00", :months)
-2
iex> date_diff("2020-06-10T00:00:00+00:00", "2020-06-13T00:00:00+00:00", :days)
-3
iex> date_diff("2020-06-10T12:50:00+00:00", "2020-06-10T09:50:00+00:00", :hours)
3
iex> date_diff("2020-06-10T12:50:00+00:00", "2020-06-10T12:00:00+00:00", :minutes)
50
iex> date_diff("2020-06-10T12:50:00+00:00", "2020-06-10T12:50:10+00:00", :seconds)
-10

date_format(date, format_string, opts \\ [])

Formats an UTC ISO8601 time string.

Expects an ISO date string, and a format string. For the syntax of the date format string, see the documentation of the Timex date formatter.

Options:

  • :locale -- Select the locale to use while formatting, for formatting month names, day names et cetera.

  • :timezone -- Select the timezone used while formatting.

  • :formatter -- Specify the the formatter module to use. Set to :strftime to select the alternative strftime formatter.

Examples:

iex> date_format("1990-10-10T00", "{YYYY}/{M}/{D}")
"1990/10/10"
iex> date_format("2012-12-12T00", "{WDfull} {D} {Mfull} {YYYY}")
"Wednesday 12 December 2012"
iex> date_format(["2012-12-12T00", "2012-12-13T00"], "{WDfull} {D} {Mfull} {YYYY}")
["Wednesday 12 December 2012", "Thursday 13 December 2012"]
iex> date_format("2022-04-29", "{YYYY}/{0M}/{D}")
"2022/04/29"

date_now(timezone \\ nil)

Returns the current time as extended ISO8601 string.

When a timezone is passed in, the current date is returned in that timezone.

date_parse(value, opts \\ [])

Parse a given date into a UTC ISO8601 time string.

The input date needs to be a string or a list of strings. The Duckling date parser is used (unless the format option is specified), so a "human input" string ("tomorrow", "in 2 hours") can be used as input.

Options:

  • :format - when format is given, parsing is done using Timex.parse, otherwise, parsing is done using Duckling.
  • :locale - the locale used for parsing (in case of Ducking parser), defaults to en_US
  • :timezone - the timezone used for parsing (in case of Ducking parser), defaults to Europe/Amsterdam

When using format:, date_parse fails with a runtime error when failing to parse the date. When using the duckling option, it returns nil when the parsing fails.

Examples:

iex> date_parse("1990-01-01")
"1990-01-01T00:00:00.000+01:00"
iex> date_parse(["1990-01-01", "1990-01-02"])
["1990-01-01T00:00:00.000+01:00", "1990-01-02T00:00:00.000+01:00"]

date_part(date, part)

Get a component of the given datetime or a list of datetimes.

The component name is one of the following:

  • :year
  • :month
  • :day
  • :hour
  • :minute
  • :second

Returns nil when an invalid part was given.

Examples:

iex> date_part("2020-06-10T00", :year)
2020
iex> date_part(["2021-06-10T00", "2022-06-10T00"], :year)
[2021, 2022]
iex> date_part("2020-06-10T00", :month)
06
iex> date_part("2020-06-10T00", :day)
10
iex> date_part("2020-06-10T12:50:00+00:00", :hour)
12
iex> date_part("2020-06-10T12:50:00+00:00", :minute)
50
iex> date_part("2020-06-10T12:50:00+00:00", :second)
0

date_set(date, opts)

Return a new date/time value with the specified fields replaced by new values.

Values are automatically validated and clamped to good values by default.

See the Timex manual.

date_shift(date, opts)

Shifts the given datetime or a list of datetimes by the given duration.

A single function for adjusting the date using various units: duration, microseconds, seconds, minutes, hours, days, weeks, months, years.

The result of applying the shift will be the same type as that of the input, with the exception of shifting DateTimes, which may result in an AmbiguousDateTime if the shift moves to an ambiguous time period for the zone of that DateTime.

Valid units are:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds
  • milliseconds
  • microseconds

See the Timex manual.

Examples:

iex> date_shift("2020-06-10T00:00:00+00:00", years: 1)
"2021-06-10T00:00:00+00:00"
iex> date_shift("2020-06-10T00:00:00+00:00", months: 2)
"2020-08-10T00:00:00+00:00"
iex> date_shift(["2020-06-10T00:00:00+00:00","2020-08-10T00:00:00+00:00"], months: 2)
["2020-08-10T00:00:00+00:00","2020-10-10T00:00:00+00:00"]
iex> date_shift("2020-06-10T00:00:00+00:00", days: 03)
"2020-06-13T00:00:00+00:00"
iex> date_shift("2020-06-10T12:50:00+00:00", hours: -3)
"2020-06-10T09:50:00+00:00"
iex> date_shift("2020-06-10T12:50:00+00:00", minutes: -50)
"2020-06-10T12:00:00+00:00"
iex> date_shift("2020-06-10T12:50:00+00:00", seconds: 10)
"2020-06-10T12:50:10+00:00"

date_truncate(date, precision)

Returns the given datetime or list of datetimes with the microsecond field truncated to the given precision.

The precision is one of the following:

  • :year
  • :month
  • :day
  • :hour
  • :minute
  • :second
  • :millisecond

Returns nil when an invalid date or invalid precision was given.

Examples:

iex> date_truncate("2020-06-10T12:50:00+00:00", :hour)
"2020-06-10T12:00:00+00:00"
iex> date_truncate(["2020-06-10", "2020-06-11"], :month)
["2020-06-01T00:00:00+00:00", "2020-06-01T00:00:00+00:00"]

relative_date(amount, unit, locale \\ "en", format \\ :default)

Formats a date to a string relative to the current moment.

Parameters:

  • amount - A number or list of numbers to use as the relative point.
  • unit - The time unit used for the formatting. Valid units are:
    • :second,
    • :minute,
    • :hour,
    • :day,
    • :week,
    • :month,
    • :year,
    • :quarter,
    • Days of the week are also units: :mon, :tue, :wed, :thu, :fri, :sat, :sun.
  • locale - the locale code for the language to format the date in, e.g. "en", "fr", "de"
  • format - the format that is used to format the date, can be :default, :narrow, or :short.

Examples:

iex> relative_date(1, :day, "en")
"tomorrow"
iex> relative_date(1, :hour, "fr")
"dans 1 heure"
iex> relative_date([1, 2, 3], :hour, "fr")
["dans 1 heure", "dans 2 heures", "dans 3 heures"]