Timex.Date

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

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

Example

iex> Date.century(Date.now) 21

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)

Multi-purpose conversion function. Converts a date to the specified time interval since Epoch. If you’d like to specify year 0 as a reference date, use one of the to_* functions.

Examples

date = Date.now
Date.convert(date, :secs) + Date.epoch(:secs) == Date.to_secs(date, :zero)  #=> true

Returns the ordinal day number of the date.

Get the name of the day corresponding to the provided number

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

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

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

Examples

Date.epoch |> Date.days_in_month  #=> 31

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 a granularity of any of

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

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

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

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

Examples

epoch()        #=> %DateTime{year: 1970, month: 1 ...}
epoch(:secs)   #=> 62167219200
epoch(:days)   #=> 719528

Determine if two dates represent the same point in time

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{...}

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

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>

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}

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

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

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

Examples

Date.epoch |> Date.iso_triplet  #=> {1970, 1, 4}

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

Examples

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

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{...}}

Convert a date to your local timezone.

See also universal/1.

Examples

Date.now |> Date.local

Get the name of the month corresponding to the provided number

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

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

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, ...]

Get current date.

Examples

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

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

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, ...]

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

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" }

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

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

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}

Get current the current datetime in UTC.

See also local/0.

Convert a date to UTC

See also local/1.

Examples

Date.now |> Date.universal

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

Examples

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

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

See also epoch/0.

Examples

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