timex

v3.6.2

timex v3.6.2 Timex.Comparable protocol View Source

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

Link to this section Summary

Types

comparable()
compare_result()
constants()
diff_result()
granularity()
t()

Functions

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

Compare two date or datetime types.

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

Get the difference between two date or datetime types.

Link to this section Types

Link to this type

comparable()

View Source 
comparable() ::
  Date.t()
  | DateTime.t()
  | NaiveDateTime.t()
  | Timex.Types.date()
  | Timex.Types.datetime()
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 type

t()

View Source 
t() :: term()

Link to this section Functions

Link to this function

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

View Source 
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 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 
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 

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