timex v3.6.1 Timex.Comparable protocol View Source

This protocol is used for comparing and diffing different date/time representations

Link to this section Summary

Functions

Compare two date or datetime types.

Get the difference between two date or datetime types.

Link to this section Types

Link to this type

compare_result() View Source
compare_result() :: -1 | 0 | 1 | {:error, term()}

Link to this type

constants() View Source
constants() :: :epoch | :zero | :distant_past | :distant_future

Link to this type

diff_result() View Source
diff_result() :: Timex.Duration.t() | integer() | {:error, term()}

Link to this type

granularity() View Source
granularity() ::
  :year
  | :years
  | :month
  | :months
  | :week
  | :weeks
  | :calendar_week
  | :calendar_weeks
  | :day
  | :days
  | :hour
  | :hours
  | :minute
  | :minutes
  | :second
  | :seconds
  | :millisecond
  | :milliseconds
  | :microsecond
  | :microseconds
  | :duration

Link to this section Functions

Link to this function

compare(a, b, granularity \\ :microsecond) View Source

Compare two date or datetime types.

You can optionally specify a comparison granularity, any of the following:

  • :year
  • :years
  • :month
  • :months
  • :week
  • :weeks
  • :calendar_week (weeks of the calendar as opposed to actual weeks in terms of days)
  • :calendar_weeks
  • :day
  • :days
  • :hour
  • :hours
  • :minute
  • :minutes
  • :second
  • :seconds
  • :millisecond
  • :milliseconds
  • :microsecond (default)
  • :microseconds
  • :duration

and the dates will be compared with the cooresponding accuracy. The default granularity is :microsecond.

  • 0: when equal
  • -1: when the first date/time comes before the second
  • 1: when the first date/time comes after the second
  • {:error, reason}: when there was a problem comparing, perhaps due to a value being passed which is not a valid date/datetime

Examples

iex> use Timex
iex> date1 = ~D[2014-03-04]
iex> date2 = ~D[2015-03-04]
iex> Timex.compare(date1, date2, :year)
-1
iex> Timex.compare(date2, date1, :year)
1
iex> Timex.compare(date1, date1)
0
Link to this function

diff(a, b, granularity \\ :microsecond) View Source

Get the difference between two date or datetime types.

You can optionally specify a diff granularity, any of the following:

  • :year
  • :years
  • :month
  • :months
  • :week
  • :weeks
  • :calendar_week (weeks of the calendar as opposed to actual weeks in terms of days)
  • :calendar_weeks
  • :day
  • :days
  • :hour
  • :hours
  • :minute
  • :minutes
  • :second
  • :seconds
  • :millisecond
  • :milliseconds
  • :microsecond (default)
  • :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.

When using granularity of :months, the number of days in the month varies. This behavior mirrors Timex.shift/2.

Examples

iex> use Timex
iex> date1 = ~D[2015-01-28]
iex> date2 = ~D[2015-02-28]
iex> Timex.diff(date1, date2, :month)
-1
iex> Timex.diff(date2, date1, :month)
1

iex> use Timex
iex> date1 = ~D[2015-01-31]
iex> date2 = ~D[2015-02-28]
iex> Timex.diff(date1, date2, :month)
-1
iex> Timex.diff(date2, date1, :month)
0