Packages
timex
3.3.0
3.7.13
3.7.12
3.7.11
3.7.9
3.7.8
3.7.7
3.7.6
3.7.5
3.7.3
3.7.2
3.7.1
3.7.0
3.6.4
3.6.3
3.6.2
retired
3.6.1
3.6.0
3.5.0
3.4.2
3.4.1
3.3.0
3.2.2
3.2.1
3.2.0
3.1.25
retired
3.1.24
3.1.23
3.1.22
3.1.21
3.1.20
3.1.19
3.1.18
3.1.17
3.1.16
3.1.15
3.1.13
3.1.12
3.1.11
3.1.10
3.1.9
3.1.8
3.1.7
3.1.6
3.1.5
3.1.4
3.1.3
3.1.2
3.1.1
3.1.0
3.0.8
3.0.7
3.0.6
3.0.5
3.0.4
3.0.3
3.0.2
3.0.1
3.0.0
2.2.1
2.1.6
2.1.5
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.0.0
1.0.2
1.0.1
1.0.0
1.0.0-rc4
1.0.0-rc3
1.0.0-rc2
1.0.0-rc1
1.0.0-pre
0.19.5
0.19.4
0.19.3
0.19.2
0.19.1
0.19.0
0.18.2
0.18.1
0.18.0
0.17.0
0.16.2
0.16.1
0.16.0
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.13.5
0.13.4
0.13.3
0.13.2
0.13.1
0.13.0
0.12.9
0.12.8
0.12.7
0.12.6
0.12.5
0.12.4
0.12.3
0.12.2
0.12.1
0.12.0
0.11.0
0.10.2
0.10.1
0.10.0
0.9.0
0.8.0
0.7.1
0.6.0
0.5.0
0.4.8
0.4.7
0.4.6
Timex is a rich, comprehensive Date/Time library for Elixir projects, with full timezone support via the :tzdata package. If you need to manipulate dates, times, datetimes, timestamps, etc., then Timex is for you!
Current section
Files
Jump to
Current section
Files
lib/comparable/comparable.ex
defprotocol Timex.Comparable do
@moduledoc """
This protocol is used for comparing and diffing different date/time representations
"""
alias Timex.Types
@type granularity :: :years | :months | :weeks | :calendar_weeks | :days |
:hours | :minutes | :seconds | :milliseconds | :microseconds |
:duration
@type constants :: :epoch | :zero | :distant_past | :distant_future
@type comparable :: Date.t | DateTime.t | NaiveDateTime.t | Types.date | Types.datetime
@type compare_result :: -1 | 0 | 1 | {:error, term}
@type diff_result :: Timex.Duration.t | integer | {:error, term}
@doc """
Compare two date or datetime types.
You can optionally specify a comparison granularity, any of the following:
- :years
- :months
- :weeks
- :calendar_weeks (weeks of the calendar as opposed to actual weeks in terms of days)
- :days
- :hours
- :minutes
- :seconds
- :milliseconds
- :microseconds (default)
- :duration
and the dates will be compared with the cooresponding accuracy.
The default granularity is :microseconds.
- 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, :years)
-1
iex> Timex.compare(date2, date1, :years)
1
iex> Timex.compare(date1, date1)
0
"""
@spec compare(comparable, comparable, granularity) :: compare_result
def compare(a, b, granularity \\ :microseconds)
@doc """
Get the difference between two date or datetime types.
You can optionally 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 (default)
- :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, :months)
-1
iex> Timex.diff(date2, date1, :months)
1
iex> use Timex
iex> date1 = ~D[2015-01-31]
iex> date2 = ~D[2015-02-28]
iex> Timex.diff(date1, date2, :months)
-1
iex> Timex.diff(date2, date1, :months)
0
"""
@spec diff(comparable, comparable, granularity) :: diff_result
def diff(a, b, granularity \\ :microseconds)
end