View Source Timex.Comparable protocol (timex v3.7.11)
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
@type comparable() :: Date.t() | DateTime.t() | NaiveDateTime.t() | Timex.Types.date() | Timex.Types.datetime()
@type compare_result() :: -1 | 0 | 1 | {:error, term()}
@type constants() :: :epoch | :zero | :distant_past | :distant_future
@type diff_result() :: Timex.Duration.t() | integer() | {:error, term()}
@type granularity() ::
:year
| :years
| :month
| :months
| :week
| :weeks
| :calendar_week
| :calendar_weeks
| :day
| :days
| :hour
| :hours
| :minute
| :minutes
| :second
| :seconds
| :millisecond
| :milliseconds
| :microsecond
| :microseconds
| :duration
@type t() :: term()
Link to this section Functions
@spec compare(comparable(), comparable(), granularity()) :: compare_result()
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 corresponding 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
- : when there was a problem comparing, perhaps due to a value being passed which is not a valid date/datetime
examples
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@spec diff(comparable(), comparable(), granularity()) :: diff_result()
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
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