Timex.Date

Module for working with dates.

Functions that produce time intervals use UNIX epoch (or simly Epoch) as the default reference date. Epoch is defined as UTC midnight of January 1, 1970.

Time intervals in this module don’t account for leap seconds.

Supported tasks:

Summary

add(date, arg2)

Add time to a date using a timestamp, i.e. {megasecs, secs, microsecs} Same as shift(date, Time.to_timestamp(5, :mins), :timestamp)

century()

Gets the current century

century(datetime)

Given a date, get the century this date is in

compare(date, date)

Compare two dates returning one of the following values:

compare(this, other, granularity)
day(date)

Returns the ordinal day number of the date

day_name(x)

Get the name of the day corresponding to the provided number

day_shortname(x)

Get the short name of the day corresponding to the provided number

day_to_num(x)

Get the day of the week corresponding to the given name

days_in_month(datetime)

Return the number of days in the month which the date falls on

days_in_month(year, month)
diff(this, other, atom3)

Calculate time interval between two dates. If the second date comes after the first one in time, return value will be positive; and negative otherwise. You must specify one of the following units:

epoch()

The date of Epoch, used as default reference date by this module and also by the Time module

epoch(atom1)

Time interval since year 0 of Epoch expressed in the specified units

equal?(this, other)

Determine if two dates represent the same point in time

from(date)

Construct a date from Erlang’s date or datetime value

from(date, tz)
from(value, type, reference \\ :epoch)

Construct a date from a time interval since Epoch or year 0

from_iso_day(day, date \\ nil)

Convert an iso ordinal day number to the day it represents in the current year. If no date is provided, a new one will be created, with the time will be set to 0:00:00, in UTC. Otherwise, the date provided will have it’s month and day reset to the date represented by the ordinal day

from_iso_triplet(triplet)

Given an ISO triplet {year, week number, weekday}, convert it to a DateTime struct

is_leap?(year)

Return a boolean indicating whether the given year is a leap year. You may pase a date or a year number

is_valid?(datetime)

Return a boolean indicating whether the given date is valid

iso_triplet(datetime)

Return a 3-tuple {year, week number, weekday} for the given date

iso_week(datetime)

Return a pair {year, week number} (as defined by ISO 8601) that date falls on

local()

Get current local date

local(date)

Convert a date to your local timezone

month_name(x)

Get the name of the month corresponding to the provided number

month_shortname(x)

Get the short name of the month corresponding to the provided number

month_to_num(x)

Get the number of the month corresponding to the given name

normalize(arg1)

Produce a valid date from a possibly invalid one

now()

Get current date

now(tz)

Get representation of the current date in seconds or days since Epoch

set(date, options)

Return a new date with the specified fields replaced by new values

shift(date, spec)

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

subtract(date, arg2)

Subtract time from a date using a timestamp, i.e. {megasecs, secs, microsecs} Same as shift(date, Time.to_timestamp(5, :mins) |> Time.invert, :timestamp)

timezone(name, datetime)

Get a TimezoneInfo object for the specified offset or name

to_days(date, reference \\ :epoch)

Convert the date to an integer number of days since Epoch or year 0

to_secs(date, reference \\ :epoch)

Convert a date to an integer number of seconds since Epoch or year 0

to_timestamp(date, reference \\ :epoch)

Convert a date to a timestamp value consumable by the Time module

universal()

Get current the current datetime in UTC

universal(date)

Convert a date to UTC

weekday(datetime)

Return weekday number (as defined by ISO 8601) of the specified date

zero()

The first day of year zero (calendar module’s default reference date)

Types

date :: {year, month, day}

year :: non_neg_integer

month :: 1 .. 12

day :: 1 .. 31

daynum :: 1 .. 366

weekday :: 1 .. 7

weeknum :: 1 .. 53

num_of_days :: 28 .. 31

hour :: 0 .. 23

minute :: 0 .. 59

second :: 0 .. 59

megaseconds :: non_neg_integer

seconds :: non_neg_integer

microseconds :: non_neg_integer

Functions

add(date, arg2)

Specs:

Add time to a date using a timestamp, i.e. {megasecs, secs, microsecs} Same as shift(date, Time.to_timestamp(5, :mins), :timestamp).

century()

Specs:

  • century :: non_neg_integer

Gets the current century

Example

iex> Date.century 21

century(datetime)

Specs:

Given a date, get the century this date is in.

Example

iex> Date.century(Date.now) 21

compare(date, date)

Specs:

Compare two dates returning one of the following values:

  • -1 — the first date comes before the second one
  • 0 — both arguments represent the same date when coalesced to the same timezone.
  • 1 — the first date comes after the second one

You can optionality specify a granularity of any of

:years :months :weeks :days :hours :mins :secs :timestamp

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

Examples

Date.compare(date1,date2,:years)

compare(this, other, granularity)

Specs:

day(date)

Specs:

Returns the ordinal day number of the date.

day_name(x)

Specs:

Get the name of the day corresponding to the provided number

day_shortname(x)

Specs:

Get the short name of the day corresponding to the provided number

day_to_num(x)

Specs:

  • day_to_num(binary | atom) :: integer

Get the day of the week corresponding to the given name.

Examples

day_to_num(“Monday”) => 1 day_to_num(“Mon”) => 1 day_to_num(“monday”) => 1 day_to_num(“mon”) => 1 day_to_num(:mon) => 1

days_in_month(datetime)

Specs:

Return the number of days in the month which the date falls on.

Examples

Date.epoch |> Date.days_in_month  #=> 31
days_in_month(year, month)
diff(this, other, atom3)

Specs:

Calculate time interval between two dates. If the second date comes after the first one in time, return value will be positive; and negative otherwise. You must specify one of the following units:

:years :months :weeks :days :hours :mins :secs :timestamp

and the result will be an integer value of those units or a timestamp.

epoch()

Specs:

The date of Epoch, used as default reference date by this module and also by the Time module.

See also zero/0.

Examples

Date.epoch |> Date.to_secs #=> 0
epoch(atom1)

Specs:

  • epoch(:secs | :days) :: integer
  • epoch(:timestamp) :: timestamp

Time interval since year 0 of Epoch expressed in the specified units.

Examples

epoch()           #=> %DateTime{year: 1970, month: 1 ...}
epoch(:timestamp) #=> {0,0,0}
epoch(:secs)      #=> 62167219200
equal?(this, other)

Specs:

Determine if two dates represent the same point in time

from(date)

Specs:

Construct a date from Erlang’s date or datetime value.

You may specify the date’s time zone as the second argument. If the argument is omitted, UTC time zone is assumed.

When passing {year, month, day} as the first argument, the resulting date will indicate midnight of that day in the specified timezone (UTC by default).

Examples

Date.from(:erlang.universaltime)             #=> %DateTime{...}
Date.from(:erlang.localtime)                 #=> %Datetime{...}
Date.from(:erlang.localtime, :local)         #=> %DateTime{...}
Date.from({2014,3,16}, Date.timezone("PST")) #=> %DateTime{...}
Date.from({2014,3,16}, "PST")                #=> %DateTime{...}
from(date, tz)

Specs:

from(value, type, reference \\ :epoch)

Specs:

Construct a date from a time interval since Epoch or year 0.

UTC time zone is assumed. This assumption can be modified by setting desired time zone using set/3 after the date is constructed.

Examples

Date.from(13, :secs)          #=> %DateTime{...}
Date.from(13, :days, :zero)   #=> %DateTime{...}

date = Date.from(Time.now, :timestamp) 
|> Date.set(:timezone, timezone(:local))      #=> yields the same value as Date.now would
from_iso_day(day, date \\ nil)

Specs:

Convert an iso ordinal day number to the day it represents in the current year. If no date is provided, a new one will be created, with the time will be set to 0:00:00, in UTC. Otherwise, the date provided will have it’s month and day reset to the date represented by the ordinal day.

Examples

180 |> Date.from_iso_day       #=> %DateTime{year: 2014, month: 6, day: 7}
180 |> Date.from_iso_day(date) #=> <modified date struct where the month and day has been set appropriately>
from_iso_triplet(triplet)

Specs:

Given an ISO triplet {year, week number, weekday}, convert it to a DateTime struct.

Examples

{2014, 5, 2} |> Date.from_iso_triplet #=> %DateTime{year: 2014, month: 2, day: 2}
is_leap?(year)

Specs:

Return a boolean indicating whether the given year is a leap year. You may pase a date or a year number.

Examples

Date.epoch |> Date.is_leap?  #=> false
Date.is_leap?(2012)          #=> true
is_valid?(datetime)

Specs:

Return a boolean indicating whether the given date is valid.

Examples

Date.from({1,1,1}, {1,1,1}) |> Date.is_valid?           #=> true
Date.from({12,13,14}) |> Date.is_valid?                 #=> false
Date.from({12,12,12, {-1,59,59}}) |> Date.is_valid?     #=> false
{{12,12,12},{1,1,1}, Date.timezone()} |> Date.is_valid? #=> true
iso_triplet(datetime)

Specs:

Return a 3-tuple {year, week number, weekday} for the given date.

Examples

Date.epoch |> Date.iso_triplet  #=> {1970, 1, 4}
iso_week(datetime)

Specs:

Return a pair {year, week number} (as defined by ISO 8601) that date falls on.

Examples

Date.epoch |> Date.iso_week  #=> {1970,1}
local()

Specs:

Get current local date.

See also universal/0.

Examples

Date.local #=> %DateTime{year: 2013, month: 3, day: 16, hour: 11, minute: 1, second: 12, timezone: %TimezoneInfo{...}}
local(date)

Specs:

Convert a date to your local timezone.

See also universal/1.

Examples

Date.now |> Date.local
month_name(x)

Specs:

  • month_name(month) :: binary

Get the name of the month corresponding to the provided number

month_shortname(x)

Specs:

  • month_shortname(month) :: binary

Get the short name of the month corresponding to the provided number

month_to_num(x)

Specs:

  • month_to_num(binary) :: integer

Get the number of the month corresponding to the given name.

Examples

month_to_num(“January”) => 1 month_to_num(“Jan”) => 1 month_to_num(“january”) => 1 month_to_num(“jan”) => 1 month_to_num(:january) => 1

normalize(arg1)

Specs:

Produce a valid date from a possibly invalid one.

All date’s components will be clamped to the minimum or maximum valid value.

Examples

{{1,13,44}, {-8,60,61}}
|> Date.normalize
|> Date.local #=> DateTime[month: 12, day: 31, hour: 0, minute: 59, second: 59, ...]
now()

Specs:

Get current date.

Examples

Date.now #=> %DateTime{year: 2013, month: 3, day: 16, hour: 11, minute: 1, second: 12, timezone: %TimezoneInfo{...}}
now(tz)

Specs:

Get representation of the current date in seconds or days since Epoch.

See convert/2 for converting arbitrary dates to various time units.

Examples

now(:secs)   #=> 1363439013
now(:days)   #=> 15780
set(date, options)

Specs:

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

Values are automatically validated and clamped to good values by default. If you wish to skip validation, perhaps for performance reasons, pass validate: false.

Values are applied in order, so if you pass [datetime: dt, date: d], the date value from date will override datetime‘s date value.

Examples

Date.now |> Date.set(date: {1,1,1})                   #=> DateTime[year: 1, month: 1, day: 1, ...]
Date.now |> Date.set(hour: 0)                         #=> DateTime[hour: 0, ...]
Date.now |> Date.set([date: {1,1,1}, hour: 30])       #=> DateTime[year: 1, month: 1, day: 1, hour: 23, ...]
Date.now |> Date.set([
  datetime: {{1,1,1}, {0,0,0}}, date: {2,2,2}
])                                                    #=> DateTime[year: 2, month: 2, day: 2, ...]
Date.now |> Date.set([minute: 74, validate: false])   #=> DateTime[minute: 74, ...]
shift(date, spec)

Specs:

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

When shifting by timestamps, microseconds are ignored.

If the list contains :month and at least one other unit, an ArgumentError is raised (due to ambiguity of such shifts). You can still shift by months separately.

If :year is present, it is applied in the last turn.

The returned date is always valid. If after adding months or years the day exceeds maximum number of days in the resulting month, that month’s last day is used.

To prevent day skew, fix up the date after shifting. For example, if you want to land on the last day of the next month, do the following:

shift(date, 1, :month) |> set(:month, 31)

Since set/3 is capping values that are out of range, you will get the correct last day for each month.

Examples

date = from({{2013,3,5}, {23,23,23}})

local(shift(date, secs: 24*3600*365))
#=> {{2014,3,5}, {23,23,23}}

local(shift(date, secs: -24*3600*(365*2 + 1)))  # +1 day for leap year 2012
#=> {{2011,3,5}, {23,23,23}}

local(shift(date, [secs: 13, day: -1, week: 2]))
#=> {{2013,3,18}, {23,23,36}}
subtract(date, arg2)

Specs:

Subtract time from a date using a timestamp, i.e. {megasecs, secs, microsecs} Same as shift(date, Time.to_timestamp(5, :mins) |> Time.invert, :timestamp).

timezone(name, datetime)

Specs:

Get a TimezoneInfo object for the specified offset or name.

When offset or name is invalid, exception is raised.

Examples

timezone(2, Date.now)      #=> { 2.0, "EET" }
timezone("+2", Date.now)   #=> { 2.0, "EET" }
timezone("EET", Date.now)  #=> { 2.0, "EET" }
to_days(date, reference \\ :epoch)

Specs:

Convert the date to an integer number of days since Epoch or year 0.

See also diff/2 if you want to specify an arbitray reference date.

Examples

to_days(now())  #=> 15780
to_secs(date, reference \\ :epoch)

Specs:

Convert a date to an integer number of seconds since Epoch or year 0.

See also diff/2 if you want to specify an arbitrary reference date.

Examples

Date.from({{1999, 1, 2}, {12,13,14}}) |> Date.to_secs  #=> 915279194
to_timestamp(date, reference \\ :epoch)

Specs:

Convert a date to a timestamp value consumable by the Time module.

See also diff/2 if you want to specify an arbitrary reference date.

Examples

Date.epoch |> Date.to_timestamp #=> {0,0,0}
universal()

Specs:

Get current the current datetime in UTC.

See also local/0.

universal(date)

Specs:

Convert a date to UTC

See also local/1.

Examples

Date.now |> Date.universal
weekday(datetime)

Specs:

Return weekday number (as defined by ISO 8601) of the specified date.

Examples

Date.epoch |> Date.weekday  #=> 4 (i.e. Thursday)
zero()

Specs:

The first day of year zero (calendar module’s default reference date).

See also epoch/0.

Examples

Date.zero |> Date.to_secs #=> 0