timex

v3.1.21

timex v3.1.21 Timex View Source

Timex

Master Hex.pm Version InchCI Coverage Status

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! It is very easy to use Timex types in place of default Erlang types, as well as Ecto types via the timex_ecto package.

The complete documentation for Timex is located here.

Migrating to Timex 3.x

See the Migrating section further down for details. If you are migrating from earlier than 2.x, please review this migration doc for 1.x to 2.x.

Timex 3.0 is a significant rewrite, in order to accommodate Elixir 1.3’s new Calendar types in a semantically correct way. The external API is mostly the same, but there are changes, many without deprecations, so please read the changelog carefully.

Getting Started

There are some brief examples on usage below, but I highly recommend you review the API docs here, there are many examples, and some extra pages with richer documentation on specific subjects such as custom formatters/parsers, etc.

Adding Timex To Your Project

To use Timex with your projects, edit your mix.exs file and add it as a dependency:

defp deps do
  [{:timex, "~> 3.0"}]
end

defp application do
  [applications: [:timex]]
end

Quickfast introduction

To use Timex, I recommend you add use Timex to the top of the module where you will be working with Timex modules, all it does is alias common types so you can work with them more comfortably. If you want to see the specific aliases added, check the top of the Timex module, in the __using__/1 macro definition.

Here’s a few simple examples:

> use Timex
> Timex.today
~D[2016-02-29]

> datetime = Timex.now
#<DateTime(2016-02-29T12:30:30.120+00:00Z Etc/UTC)

> Timex.now("America/Chicago")
#<DateTime(2016-02-29T06:30:30.120-06:00 America/Chicago)

> Duration.now
#<Duration(P46Y6M24DT21H57M33.977711S)>

> {:ok, default_str} = Timex.format(datetime, "{ISO:Extended}")
{:ok, "2016-02-29T12:30:30.120+00:00"}

> {:ok, relative_str} = Timex.shift(datetime, minutes: -3) |> Timex.format("{relative}", :relative)
{:ok, "3 minutes ago"}

> strftime_str = Timex.format!(datetime, "%FT%T%:z", :strftime)
"2016-02-29T12:30:30+00:00"

> Timex.parse(default_str, "{ISO:Extended}")
{:ok, #<DateTime(2016-02-29T12:30:30.120+00:00 Etc/Utc)}

> Timex.parse!(strftime_str, "%FT%T%:z", :strftime)
#<DateTime(2016-02-29T12:30:30.120+00:00 Etc/Utc)

> Duration.diff(Duration.now, Duration.zero, :days)
16850

> Timex.shift(date, days: 3)
~D[2016-03-03]

> Timex.shift(datetime, hours: 2, minutes: 13)
#<DateTime(2016-02-29T14:43:30.120Z Etc/UTC)>

> timezone = Timezone.get("America/Chicago", Timex.now)
#<TimezoneInfo(America/Chicago - CDT (-06:00:00))>

> Timezone.convert(datetime, timezone)
#<DateTime(2016-02-29T06:30:30.120-06:00 America/Chicago)>

> Timex.before?(Timex.today, Timex.shift(Timex.today, days: 1))
true

> Timex.before?(Timex.shift(Timex.today, days: 1), Timex.today)
false

There are a ton of other functions, all of which work with Erlang datetime tuples, Date, NaiveDateTime, and DateTime. The Duration module contains functions for working with Durations, including Erlang timestamps (such as those returned from :timer.tc)

Extensibility

Timex exposes a number of extension points for you, in order to accommodate different use cases:

Timex itself defines it’s core operations on the Date, DateTime, and NaiveDateTime types using the Timex.Protocol protocol. From there, all other Timex functionality is derived. If you have custom date/datetime types you want to use with Timex, this is the protocol you would need to implement.

Timex also defines a Timex.Comparable protocol, which you can extend to add comparisons to custom date/datetime types.

You can provide your own formatter/parser for datetime strings by implementing the Timex.Format.DateTime.Formatter and/or Timex.Parse.DateTime.Parser behaviours, depending on your needs.

Common Issues

Warning: Timex functions of the form iso_* behave based on how the ISO calendar represents dates/times and not the ISO8601 date format. This confusion has occurred before, and it’s important to note this!

  • If you need to use Timex from within an escript, add {:tzdata, "~> 0.1.8", override: true} to your deps, more recent versions of :tzdata are unable to work in an escript because of the need to load ETS table files from priv, and due to the way ETS loads these files, it’s not possible to do so.

Automatic time zone updates

Timex includes the Tzdata library for time zone data. Tzdata has an automatic update capability that fetches updates from IANA and which is enabled by default; if you want to disable it, check the Tzdata documentation for details.

Migrating

If you have been using Timex pre-3.x, and you are looking to migrate, it will be fairly painless as long as you review the CHANGELOG.md file and make note of anything that has changed which you are using. In almost every single case, the functionality has simply moved, or is accessed slightly differently. In some cases behaviour has changed, but the old behaviour can be achieved manually. For those things which were removed or are no longer available, it is almost certainly because those things are no longer recommended, or no longer make sense for this library. If I have missed something, or there is a good justification for re-adding something which was removed, I’m always open to discussing it on the issue tracker.

Overview of 3.x changes

Please see the CHANGELOG.md file for the list of all changes made, below are a brief recap of the major points, and instructions on how to migrate your existing Timex-based code to 3.x.

  • Virtually all of Timex’s API is consolidated around three modules: Timex, Duration, and Interval. There are public APIs in other modules of course, but most everything you do can be done via one of those three.
  • All Timex-provided types have been removed, with the exception of Time which has been renamed to Duration to better fit it’s purpose, TimezoneInfo, which is still used internally, and accessible externally, and AmbiguousDateTime, which is still required when dealing with ambiguous DateTime structs. Date and DateTime are now part of Elixir 1.3, and NaiveDateTime has been added as a first class type as well.
  • Conversions have been rehashed, and are now accessed via the Timex module: to_date, to_datetime, to_naive_datetime, to_erl, to_unix, to_gregorian_seconds, and to_gregorian_microseconds. Use these to convert back and forth between types. With very few exceptions, there are no from_* conversions. You must construct a standard type either with the standard library functions (such as NaiveDateTime.new), or by converting from another standard type (i.e. Erlang datetime tuple to NaiveDateTime).

A variety of improvements came about as well:

  • Microsecond precision everywhere it can be maintained
  • Various bug fixes from the 2.x release which were held back
  • A lot of code clean up
  • Faster compilation
  • Fixed typespecs, docs, and tests across the board
  • Added Julian calendar support

Roadmap

The following are an unordered list of things I plan for Timex in the future, if you have specific requests, please open an issue with “RFC” in the title, and we can discuss it, and hopefully get input from the community.

  • 100% test coverage (well under way!)
  • QuickCheck tests (haven’t started this, but I really want to start ASAP)
  • {ASP.NET} formatting/parsing token for interop with .NET services (probably in the next release)
  • Relative time formatter/parser, along the lines of Moment.js’s fromNow, toNow, timeTo, and timeFrom formatting functions.
  • Calendar time formatter/parser, along the lines of Moment.js’s calendar time formatter
  • Recurring dates/times API

License

This software is licensed under the MIT license.

Link to this section Summary

Types

set_options()
shift_options()

Functions

add(date, duration)

Add time to a date using a Duration Same as shift(date, Duration.from_minutes(5), :duration)

after?(a, b)

Returns a boolean indicating whether the first Timex.Comparable occurs after the second

before?(a, b)

Returns a boolean indicating whether the first Timex.Comparable occurs before the second

beginning_of_day(datetime)

Returns a DateTime representing the beginning of the day

beginning_of_month(datetime)

Given a date returns a date at the beginning of the month

beginning_of_month(year, month)

Same as beginning_of_month/1, except takes year and month as distinct arguments

beginning_of_quarter(datetime)

Given a date returns a date at the beginning of the quarter

beginning_of_week(date)

Shifts the date to the beginning of the week

beginning_of_week(date, weekstart)

See Timex.Protocol.beginning_of_week/2

beginning_of_year(year)

Given a date or a number create a date at the beginning of that year

between?(a, start, ending)

Returns a boolean indicating whether the first Timex.Comparable occurs between the second and third

century()

Gets the current century

century(year)

Given a date, get the century this date is in

compare(a, b)

See docs for compare/3

compare(a, b, granularity)

Compare two Timex.Comparable values, returning one of the following values

day(datetime)

Returns the ordinal day number of the date

day_name(num)

Get the name of the day corresponding to the provided number

day_shortname(num)

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

day_to_num(arg1)

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)

Same as days_in_month/2, except takes year and month as distinct arguments

days_to_beginning_of_week(date, weekstart \\ 1)

Number of days to the beginning of the week

days_to_end_of_week(date, weekstart \\ :mon)

Number of days to the end of the week

diff(a, b)

See docs for diff/3

diff(a, b, granularity)

Calculate time interval between two dates. The result will be a signed integer, negative if the first date/time comes before the second, and positive if the first date/time comes after the second

end_of_day(datetime)

Returns a DateTime representing the end of the day

end_of_month(datetime)

Given a date returns a date at the end of the month

end_of_month(year, month)

Same as end_of_month/1, except takes year and month as distinct arguments

end_of_quarter(datetime)

Given a date or a year and month returns a date at the end of the quarter

end_of_quarter(year, month)

Same as end_of_quarter/1, except takes year and month as distinct arguments

end_of_week(datetime)

Returns a Date or a DateTime representing the end of the week, depending on the input, i.e. if you pass a date/time value which represents just a date, you will get back a Date, if both a date and time are present, you will get back a DateTime

end_of_week(datetime, weekstart)

See Timex.Protocol.end_of_week/2

end_of_year(year)

Given a date or a number create a date at the end of that year

epoch()

Returns a Date representing the start of the UNIX epoch

equal?(a, a, granularity \\ :seconds)

Returns a boolean indicating whether the two Timex.Comparable values are equivalent

format(datetime, format_string)

Formats a date/time value using the given format string (and optional formatter)

format(datetime, format_string, formatter)

Same as format/2, except using a custom formatter

format!(datetime, format_string)

Same as format/2, except format! raises on error

format!(datetime, format_string, formatter)

Same as format/3, except format! raises on error

format_duration(timestamp)

Formats an Erlang timestamp using the ISO-8601 duration format, or optionally, with a custom formatter of your choosing

format_duration(timestamp, formatter)

Same as format_duration/1, except it also accepts a formatter

from_iso_day(day)

Convert an iso ordinal day number to the day it represents in the current year

from_iso_day(day, year)

Same as from_iso_day/1, except you can expect the following based on the second parameter

from_iso_triplet(arg)

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

from_now(datetime)

Formats a DateTime using a fuzzy relative duration, from now

from_now(datetime, locale)

Formats a DateTime using a fuzzy relative duration, with a reference datetime other than now

from_now(datetime, reference_date, locale)

Formats a DateTime using a fuzzy relative duration, with a reference datetime other than now, translated using the given locale

from_unix(secs, unit \\ :seconds)

Delegates to DateTime.from_unix!/2. To recap the docs

is_leap?(year)

See Timex.Protocol.is_leap?/1

is_valid?(datetime)

Return a boolean indicating whether the given date is valid

is_valid_time?(arg1)

Returns a boolean indicating whether the provided term represents a valid time, valid times are one of

is_valid_timezone?(timezone)

Returns a boolean indicating whether the provided term represents a valid timezone, valid timezones are one of

iso_triplet(datetime)

Return a 3-tuple {year, week number, weekday} for the given Date/DateTime

iso_week(datetime)

Return a pair {year, week number} (as defined by ISO 8601) that the given Date/DateTime value falls on

iso_week(year, month, day)

Same as iso_week/1, except this takes a year, month, and day as distinct arguments

lformat(datetime, format_string, locale)

Same as format/2, except takes a locale name to translate text to

lformat(datetime, format_string, locale, formatter)

Same as lformat/3, except takes a formatter as it’s last argument

lformat!(datetime, format_string, locale)

Same as lformat/3, except local_format! raises on error

lformat!(datetime, format_string, locale, formatter)

Same as lformat/4, except local_format! raises on error

lformat_duration(timestamp, locale)

Same as format_duration/1, except takes a locale for use in translation

lformat_duration(timestamp, locale, formatter)

Same as lformat_duration/2, except takes a formatter as an argument

local()

Returns a DateTime representing the current moment in time in the local timezone

local(date)

Returns a DateTime representing the given date/time in the local timezone

month_name(num)

Get the name of the month corresponding to the provided number

month_shortname(num)

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

month_to_num(arg1)

Get the number of the month corresponding to the given name

normalize(atom, year)

Given a unit to normalize, and the value to normalize, produces a valid value for that unit, clamped to whatever boundaries are defined for that unit

now()

Returns a DateTime representing the current moment in time in UTC

now(tz)

Returns a DateTime representing the current moment in time in the provided timezone

parse(datetime_string, format_string)

Parses a datetime string into a DateTime struct, using the provided format string (and optional tokenizer)

parse(datetime_string, format_string, tokenizer)

See Timex.Parse.DateTime.Parser.parse/3

parse!(datetime_string, format_string)

Same as parse/2 and parse/3, except parse! raises on error

parse!(datetime_string, format_string, tokenizer)

See Timex.Parse.DateTime.Parser.parse!/3

quarter(month)

Returns what quarter of the year the given date/time falls in

set(date, options)

Return a new date/time value with the specified fields replaced by new values

shift(date, options)

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

start(type, args)

Called when an application is started

subtract(date, duration)

Subtract time from a date using a Duration Same as shift(date, Duration.from_minutes(5) |> Duration.invert, :timestamp)

timezone(tz, datetime)

Get a TimezoneInfo object for the specified offset or name

timezones()

Returns a list of all valid timezone names in the Olson database

to_date(date)

Convert a date/time value to a Date struct

to_datetime(from)

Convert a date/time value and timezone name to a DateTime struct. If the DateTime is ambiguous and cannot be resolved, an AmbiguousDateTime will be returned, allowing the developer to choose which of the two choices is desired

to_datetime(from, timezone)

See Timex.Protocol.to_datetime/2

to_erl(date)

Convert a date/time value to it’s Erlang representation

to_gregorian_microseconds(datetime)

Convert a date/time value to gregorian microseconds (microseconds since start of year zero)

to_gregorian_seconds(datetime)

Convert a date/time value to gregorian seconds (seconds since start of year zero)

to_julian(datetime)

Convert a date/time value to a Julian calendar date number

to_naive_datetime(date)

Convert a date/time value to a NaiveDateTime struct

to_unix(datetime)

Convert a date/time value to seconds since the UNIX epoch

today()

Returns a Date representing the current day in UTC

validate_format(format_string)

Given a format string, validates that the format string is valid for the Default formatter

validate_format(format_string, formatter)

See Timex.Format.DateTime.Formatter.validate/2

week_of_month(datetime)

Given a Convertable, this function returns the week number of the date provided, starting at 1

week_of_month(year, month, day)

Same as week_of_month/1, except takes year, month, and day as distinct arguments

weekday(datetime)

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

zero()

Returns a Date representing the start of the Gregorian epoch

Link to this section Types

Link to this type set_options() View Source 
set_options() :: [validate: boolean, datetime: Timex.Types.datetime, date: Timex.Types.date, year: Timex.Types.year, month: Timex.Types.month, day: Timex.Types.day, hour: Timex.Types.hour, minute: Timex.Types.minute, second: Timex.Types.second, microsecond: Timex.Types.microsecond]
Link to this type shift_options() View Source 
shift_options() :: [microseconds: integer, milliseconds: integer, seconds: integer, minutes: integer, hours: integer, days: integer, weeks: integer, months: integer, years: integer]

Link to this section Functions

Link to this function add(date, duration) View Source 
add(Timex.Convertable.t, Timex.Duration.t) ::
  Timex.Types.valid_datetime |
  Timex.AmbiguousDateTime.t |
  {:error, term}

Add time to a date using a Duration Same as shift(date, Duration.from_minutes(5), :duration).

Link to this function after?(a, b) View Source 
after?(Timex.Comparable.comparable, Timex.Comparable.comparable) ::
  boolean |
  {:error, term}

Returns a boolean indicating whether the first Timex.Comparable occurs after the second

Link to this function before?(a, b) View Source 
before?(Timex.Comparable.comparable, Timex.Comparable.comparable) ::
  boolean |
  {:error, term}

Returns a boolean indicating whether the first Timex.Comparable occurs before the second

Link to this function beginning_of_day(datetime) View Source 
beginning_of_day(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Returns a DateTime representing the beginning of the day

Examples 

iex> date = Timex.to_datetime({{2015, 1, 1}, {13, 14, 15}}, "Etc/UTC")
iex> Timex.beginning_of_day(date)
Timex.to_datetime({{2015, 1, 1}, {0, 0, 0}}, "Etc/UTC")

iex> date = ~D[2015-01-01]
...> Timex.beginning_of_day(date)
~D[2015-01-01]
Link to this function beginning_of_month(datetime) View Source 
beginning_of_month(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date returns a date at the beginning of the month.

iex> date = Timex.to_datetime({{2015, 6, 15}, {12,30,0}}, "Europe/Paris")
iex> Timex.beginning_of_month(date)
Timex.to_datetime({{2015, 6, 1}, {0, 0, 0}}, "Europe/Paris")
Link to this function beginning_of_month(year, month) View Source 
beginning_of_month(Timex.Types.year, Timex.Types.month) ::
  Date.t |
  {:error, term}

Same as beginning_of_month/1, except takes year and month as distinct arguments

Link to this function beginning_of_quarter(datetime) View Source 
beginning_of_quarter(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date returns a date at the beginning of the quarter.

iex> date = Timex.to_datetime({{2015, 6, 15}, {12,30,0}}, "America/Chicago")
iex> Timex.beginning_of_quarter(date)
Timex.to_datetime({{2015, 4, 1}, {0, 0, 0}}, "America/Chicago")
Link to this function beginning_of_week(date) View Source

Shifts the date to the beginning of the week

The weekstart can between 1..7, an atom e.g. :mon, or a string e.g. “Monday”

Examples 

iex> date = ~N[2015-11-30T13:30:30] # Monday 30th November
iex> Timex.beginning_of_week(date)
~N[2015-11-30T00:00:00]

iex> date = ~D[2015-11-30] # Monday 30th November
iex> Timex.beginning_of_week(date, :sun)
~D[2015-11-29]
Link to this function beginning_of_week(date, weekstart) View Source 
beginning_of_week(Timex.Types.valid_datetime, Timex.Types.weekstart) ::
  Timex.Types.valid_datetime |
  {:error, term}

See Timex.Protocol.beginning_of_week/2.

Link to this function beginning_of_year(year) View Source 
beginning_of_year(Timex.Types.year | Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date or a number create a date at the beginning of that year

Examples

iex> date = ~N[2015-06-15T00:00:00]
iex> Timex.beginning_of_year(date)
~N[2015-01-01T00:00:00]

iex> Timex.beginning_of_year(2015)
~D[2015-01-01]
Link to this function between?(a, start, ending) View Source 
between?(Timex.Comparable.comparable, Timex.Comparable.comparable, Timex.Comparable.comparable) ::
  boolean |
  {:error, term}

Returns a boolean indicating whether the first Timex.Comparable occurs between the second and third

Link to this function century() View Source 
century() :: non_neg_integer

Gets the current century

Examples 

iex> Elixir.Timex.century
21
Link to this function century(year) View Source 
century(Timex.Types.year | Timex.Types.valid_datetime) :: non_neg_integer

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

Examples 

iex> Timex.today |> Elixir.Timex.century
21
iex> Timex.now |> Elixir.Timex.century
21
iex> Elixir.Timex.century(2016)
21
Link to this function compare(a, b, granularity) View Source 
compare(Timex.Comparable.comparable, Timex.Comparable.comparable, Timex.Comparable.granularity) ::
  Timex.Comparable.compare_result |
  {:error, term}

Compare two Timex.Comparable values, 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 provide a few reference constants for the second argument:

  • :epoch will compare the first parameter against the Date/DateTime of the first moment of the UNIX epoch
  • :zero will compare the first parameter against the Date/DateTime of the first moment of year zero
  • :distant_past will compare the first parameter against a date/time infinitely in the past (i.e. it will always return 1)
  • :distant_future will compare the first parameter against a date/time infinitely in the future (i.e. it will always return -1)

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.

Examples 

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
Link to this function day(datetime) View Source 
day(Timex.Types.valid_datetime) ::
  Timex.Types.daynum |
  {:error, term}

Returns the ordinal day number of the date.

Examples 

iex> Timex.day(~D[2015-06-26])
177
Link to this function day_name(num) View Source 
day_name(Timex.Types.weekday) ::
  String.t |
  {:error, :invalid_weekday_number}

Get the name of the day corresponding to the provided number

Examples 

iex> Elixir.Timex.day_name(1)
"Monday"
iex> Elixir.Timex.day_name(0)
{:error, :invalid_weekday_number}
Link to this function day_shortname(num) View Source 
day_shortname(Timex.Types.weekday) ::
  String.t |
  {:error, :invalid_weekday_number}

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

Examples 

iex> Elixir.Timex.day_shortname(1)
"Mon"
iex> Elixir.Timex.day_shortname(0)
{:error, :invalid_weekday_number}
Link to this function day_to_num(arg1) View Source 
day_to_num(binary | atom) ::
  integer |
  {:error, :invalid_day_name}

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

Examples 

iex> Elixir.Timex.day_to_num("Monday")
1
iex> Elixir.Timex.day_to_num("monday")
1
iex> Elixir.Timex.day_to_num("Mon")
1
iex> Elixir.Timex.day_to_num("mon")
1
iex> Elixir.Timex.day_to_num(:mon)
1
Link to this function days_in_month(datetime) View Source 
days_in_month(Timex.Types.valid_datetime) ::
  Timex.Types.num_of_days |
  {:error, term}

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

Examples 

iex> Timex.days_in_month(~D[1970-01-01])
31
Link to this function days_in_month(year, month) View Source 
days_in_month(Timex.Types.year, Timex.Types.month) ::
  Timex.Types.num_of_days |
  {:error, term}

Same as days_in_month/2, except takes year and month as distinct arguments

Link to this function days_to_beginning_of_week(date, weekstart \\ 1) View Source 
days_to_beginning_of_week(Timex.Types.valid_datetime, Timex.Types.weekstart) ::
  integer |
  {:error, term}

Number of days to the beginning of the week

The weekstart can between 1..7, an atom e.g. :mon, or a string e.g. “Monday”

Examples 

iex> date = ~D[2015-11-30] # Monday 30th November
iex> Timex.days_to_beginning_of_week(date)
0

iex> date = ~D[2015-11-30] # Monday 30th November
iex> Timex.days_to_beginning_of_week(date, :sun)
1
Link to this function days_to_end_of_week(date, weekstart \\ :mon) View Source 
days_to_end_of_week(Timex.Types.valid_datetime, Timex.Types.weekstart) ::
  integer |
  {:error, term}

Number of days to the end of the week.

The weekstart can between 1..7, an atom e.g. :mon, or a string e.g. “Monday”

Examples 

Week starting Monday
iex> date = ~D[2015-11-30] # Monday 30th November
iex> Timex.days_to_end_of_week(date)
6

Week starting Sunday
iex> date = ~D[2015-11-30] # Monday 30th November
iex> Timex.days_to_end_of_week(date, :sun)
5
Link to this function diff(a, b) View Source 
diff(Timex.Comparable.comparable, Timex.Comparable.comparable) ::
  Timex.Types.timestamp |
  {:error, term}

See docs for diff/3

Link to this function diff(a, b, granularity) View Source 
diff(Timex.Comparable.comparable, Timex.Comparable.comparable, Timex.Comparable.granularity) ::
  Timex.Duration.t |
  integer |
  {:error, term}

Calculate time interval between two dates. The result will be a signed integer, negative if the first date/time comes before the second, and positive if the first date/time comes after the second.

You must specify one of the following units:

  • :years
  • :months
  • :calendar_weeks (weeks of the calendar as opposed to actual weeks in terms of days)
  • :weeks
  • :days
  • :hours
  • :minutes
  • :seconds
  • :duration

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

Link to this function end_of_day(datetime) View Source 
end_of_day(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Returns a DateTime representing the end of the day

Examples 

iex> date = ~N[2015-01-01T13:14:15]
...> Timex.end_of_day(date)
~N[2015-01-01T23:59:59.999999]
Link to this function end_of_month(datetime) View Source 
end_of_month(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date returns a date at the end of the month.

iex> date = ~N[2015-06-15T12:30:00Z]
iex> Timex.end_of_month(date)
~N[2015-06-30T23:59:59.999999Z]
Link to this function end_of_month(year, month) View Source 
end_of_month(Timex.Types.year, Timex.Types.month) :: Date.t

Same as end_of_month/1, except takes year and month as distinct arguments

Examples 

iex> Timex.end_of_month(2016, 2)
~D[2016-02-29]
Link to this function end_of_quarter(datetime) View Source 
end_of_quarter(Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date or a year and month returns a date at the end of the quarter.

iex> date = ~N[2015-06-15T12:30:00]
...> Timex.end_of_quarter(date)
~N[2015-06-30T23:59:59.999999]

iex> Timex.end_of_quarter(2015, 4)
~D[2015-06-30]
Link to this function end_of_quarter(year, month) View Source 
end_of_quarter(Timex.Types.year, Timex.Types.month) ::
  Date.t |
  {:error, term}

Same as end_of_quarter/1, except takes year and month as distinct arguments

Link to this function end_of_week(datetime) View Source

Returns a Date or a DateTime representing the end of the week, depending on the input, i.e. if you pass a date/time value which represents just a date, you will get back a Date, if both a date and time are present, you will get back a DateTime

The weekstart can between 1..7, an atom e.g. :mon, or a string e.g. “Monday”

Examples 

iex> date = ~N[2015-11-30T13:30:30] # Monday 30th November
...> Timex.end_of_week(date)
~N[2015-12-06T23:59:59.999999]

iex> date = ~D[2015-11-30] # Monday 30th November
...> Timex.end_of_week(date, :sun)
~D[2015-12-05]
Link to this function end_of_week(datetime, weekstart) View Source 
end_of_week(Timex.Types.valid_datetime, Timex.Types.weekstart) ::
  Timex.Types.valid_datetime |
  {:error, term}

See Timex.Protocol.end_of_week/2.

Link to this function end_of_year(year) View Source 
end_of_year(Timex.Types.year | Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Given a date or a number create a date at the end of that year

Examples

iex> date = ~N[2015-06-15T00:00:00]
iex> Timex.end_of_year(date)
~N[2015-12-31T23:59:59.999999]

iex> Timex.end_of_year(2015)
~D[2015-12-31]
Link to this function epoch() View Source 
epoch() :: Date.t

Returns a Date representing the start of the UNIX epoch

Link to this function equal?(a, a, granularity \\ :seconds) View Source 
equal?(Timex.Comparable.comparable, Timex.Comparable.comparable, Timex.Comparable.granularity) ::
  boolean |
  {:error, :badarg}

Returns a boolean indicating whether the two Timex.Comparable values are equivalent.

Equality here implies that the two Comparables represent the same moment in time (with the given granularity), not equality of the data structure.

The options for granularity is the same as for compare/3, defaults to :seconds.

Examples 

iex> date1 = ~D[2014-03-01]
...> date2 = ~D[2014-03-01]
...> Elixir.Timex.equal?(date1, date2)
true

iex> date1 = ~D[2014-03-01]
...> date2 = Timex.to_datetime({2014, 3, 1}, "Etc/UTC")
...> Elixir.Timex.equal?(date1, date2)
true
Link to this function format(datetime, format_string) View Source 
format(Timex.Convertable.t, format :: String.t) ::
  {:ok, String.t} |
  {:error, term}

Formats a date/time value using the given format string (and optional formatter).

See Timex.Format.DateTime.Formatters.Default or Timex.Format.DateTime.Formatters.Strftime for documentation on the syntax supported by those formatters.

To use the Default formatter, simply call format/2. To use the Strftime formatter, you can either alias and pass Strftime by module name, or as a shortcut, you can pass :strftime instead.

Formatting uses the Convertable protocol to convert non-DateTime structs to DateTime structs.

Examples 

iex> date = ~D[2016-02-29]
...> Timex.format!(date, "{YYYY}-{0M}-{D}")
"2016-02-29"

iex> datetime = Timex.to_datetime({{2016,2,29},{22,25,0}}, "Etc/UTC")
...> Timex.format!(datetime, "{ISO:Extended}")
"2016-02-29T22:25:00+00:00"
Link to this function format(datetime, format_string, formatter) View Source 
format(Timex.Convertable.t, format :: String.t, formatter :: atom) ::
  {:ok, String.t} |
  {:error, term}

Same as format/2, except using a custom formatter

Examples 

iex> use Timex
...> datetime = Timex.to_datetime({{2016,2,29},{22,25,0}}, "America/Chicago")
iex> Timex.format!(datetime, "%FT%T%:z", :strftime)
"2016-02-29T22:25:00-06:00"
Link to this function format!(datetime, format_string) View Source 
format!(Timex.Convertable.t, format :: String.t) ::
  String.t |
  no_return

Same as format/2, except format! raises on error.

See format/2 docs for usage examples.

Link to this function format!(datetime, format_string, formatter) View Source 
format!(Timex.Convertable.t, format :: String.t, formatter :: atom) ::
  String.t |
  no_return

Same as format/3, except format! raises on error.

See format/3 docs for usage examples

Link to this function format_duration(timestamp) View Source 
format_duration(Timex.Types.timestamp) ::
  String.t |
  {:error, term}

Formats an Erlang timestamp using the ISO-8601 duration format, or optionally, with a custom formatter of your choosing.

See Timex.Format.Duration.Formatters.Default or Timex.Format.Duration.Formatters.Humanized for documentation on the specific formatter behaviour.

To use the Default formatter, simply call format_duration/2. To use the Humanized formatter, you can either alias and pass Humanized by module name, or as a shortcut, you can pass :humanized instead.

Examples 

iex> use Timex
...> duration = Duration.from_seconds(Timex.to_unix({2016, 2, 29}))
...> Timex.format_duration(duration)
"P46Y2M10D"

iex> use Timex
...> duration = Duration.from_seconds(Timex.to_unix({2016, 2, 29}))
...> Timex.format_duration(duration, :humanized)
"46 years, 2 months, 1 week, 3 days"

iex> use Timex
...> datetime = Duration.from_seconds(Timex.to_unix(~N[2016-02-29T22:25:00]))
...> Timex.format_duration(datetime, :humanized)
"46 years, 2 months, 1 week, 3 days, 22 hours, 25 minutes"
Link to this function format_duration(timestamp, formatter) View Source 
format_duration(Timex.Types.timestamp, atom) ::
  String.t |
  {:error, term}

Same as format_duration/1, except it also accepts a formatter

Link to this function from_iso_day(day) View Source 
from_iso_day(non_neg_integer) :: Date.t | {:error, term}

Convert an iso ordinal day number to the day it represents in the current year.

## Examples

iex> %Date{:year => year} = Timex.from_iso_day(180)
...> %Date{:year => todays_year} = Timex.today()
...> year == todays_year
true
Link to this function from_iso_day(day, year) View Source 
from_iso_day(non_neg_integer, Timex.Types.year | Timex.Types.valid_datetime) ::
  Timex.Types.valid_datetime |
  {:error, term}

Same as from_iso_day/1, except you can expect the following based on the second parameter:

  • If an integer year is given, the result will be a Date struct
  • For any date/time value, the result will be in the same format (i.e. Date -> Date)

In all cases, the resulting value will be the date representation of the provided ISO day in that year

Examples

Creating a Date from the given day

iex> use Timex
...> expected = ~D[2015-06-29]
...> (expected === Timex.from_iso_day(180, 2015))
true

Creating a Date/DateTime from the given day

iex> use Timex
...> expected = Timex.to_datetime({{2015, 6, 29}, {0,0,0}}, "Etc/UTC")
...> beginning = Timex.to_datetime({{2015,1,1}, {0,0,0}}, "Etc/UTC")
...> (expected === Timex.from_iso_day(180, beginning))
true

Shifting a Date/DateTime to the given day

iex> use Timex
...> date = Timex.to_datetime({{2015,6,26}, {12,0,0}}, "Etc/UTC")
...> expected = Timex.to_datetime({{2015, 6, 29}, {12,0,0}}, "Etc/UTC")
...> (Timex.from_iso_day(180, date) === expected)
true
Link to this function from_iso_triplet(arg) View Source 
from_iso_triplet(Timex.Types.iso_triplet) ::
  Date.t |
  {:error, term}

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

Examples 

iex> expected = Timex.to_date({2014, 1, 28})
iex> Timex.from_iso_triplet({2014, 5, 2}) === expected
true
Link to this function from_now(datetime) View Source 
from_now(Timex.Convertable.t) :: String.t | {:error, term}

Formats a DateTime using a fuzzy relative duration, from now.

Examples 

iex> use Timex
...> Timex.from_now(Timex.shift(DateTime.utc_now(), days: 2, hours: 1))
"in 2 days"

iex> use Timex
...> Timex.from_now(Timex.shift(DateTime.utc_now(), days: -2))
"2 days ago"
Link to this function from_now(datetime, locale) View Source 
from_now(Timex.Types.valid_datetime, String.t) ::
  String.t |
  {:error, term}
from_now(Timex.Convertable.t, Timex.Convertable.t) ::
  String.t |
  {:error, term}

Formats a DateTime using a fuzzy relative duration, with a reference datetime other than now

Link to this function from_now(datetime, reference_date, locale) View Source 
from_now(Timex.Types.valid_datetime, Timex.Types.valid_datetime, String.t) ::
  String.t |
  {:error, term}

Formats a DateTime using a fuzzy relative duration, with a reference datetime other than now, translated using the given locale

Link to this function from_unix(secs, unit \\ :seconds) View Source 
from_unix(secs :: non_neg_integer, :native | System.time_unit) ::
  DateTime.t |
  no_return

Delegates to DateTime.from_unix!/2. To recap the docs:

Converts the given Unix time to DateTime.

The integer can be given in different units according to System.convert_time_unit/3 and it will be converted to microseconds internally. Defaults to :seconds.

Unix times are always in UTC and therefore the DateTime will be returned in UTC.

Link to this function is_leap?(year) View Source 
is_leap?(Timex.Types.valid_datetime | Timex.Types.year) ::
  boolean |
  {:error, term}

See Timex.Protocol.is_leap?/1.

Link to this function is_valid?(datetime) View Source 
is_valid?(Timex.Convertable.t) :: boolean

Return a boolean indicating whether the given date is valid.

Examples 

iex> use Timex
...> Timex.is_valid?(~N[0001-01-01T01:01:01])
true

iex> use Timex
...> %Date{year: 1, day: 1, month: 13} |> Elixir.Timex.is_valid?
false
Link to this function is_valid_time?(arg1) View Source 
is_valid_time?(term) :: boolean

Returns a boolean indicating whether the provided term represents a valid time, valid times are one of:

  • {hour, min, sec}
  • {hour, min, sec, ms}
Link to this function is_valid_timezone?(timezone) View Source 
is_valid_timezone?(term) :: boolean

Returns a boolean indicating whether the provided term represents a valid timezone, valid timezones are one of:

  • TimezoneInfo struct
  • A timezone name as a string
  • :utc as a shortcut for the UTC timezone
  • :local as a shortcut for the local timezone
  • A number representing an offset from UTC
Link to this function iso_triplet(datetime) View Source 
iso_triplet(Timex.Types.valid_datetime) ::
  {Timex.Types.year, Timex.Types.weeknum, Timex.Types.weekday} |
  {:error, term}

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

Examples 

iex> Elixir.Timex.iso_triplet(Timex.epoch)
{1970, 1, 4}
Link to this function iso_week(datetime) View Source 
iso_week(Timex.Types.valid_datetime) ::
  {Timex.Types.year, Timex.Types.weeknum} |
  {:error, term}

Return a pair {year, week number} (as defined by ISO 8601) that the given Date/DateTime value falls on.

Examples 

iex> Elixir.Timex.iso_week({1970, 1, 1})
{1970,1}
Link to this function iso_week(year, month, day) View Source 
iso_week(Timex.Types.year, Timex.Types.month, Timex.Types.day) ::
  {Timex.Types.year, Timex.Types.weeknum} |
  {:error, term}

Same as iso_week/1, except this takes a year, month, and day as distinct arguments.

Examples 

iex> Elixir.Timex.iso_week(1970, 1, 1)
{1970,1}
Link to this function lformat(datetime, format_string, locale) View Source 
lformat(Timex.Convertable.t, format :: String.t, locale :: String.t) ::
  {:ok, String.t} |
  {:error, term}

Same as format/2, except takes a locale name to translate text to.

Translations only apply to units, relative time phrases, and only for the locales in the list of supported locales in the Timex documentation.

Link to this function lformat(datetime, format_string, locale, formatter) View Source 
lformat(Timex.Convertable.t, format :: String.t, locale :: String.t, formatter :: atom) ::
  {:ok, String.t} |
  {:error, term}

Same as lformat/3, except takes a formatter as it’s last argument.

Translations only apply to units, relative time phrases, and only for the locales in the list of supported locales in the Timex documentation.

Link to this function lformat!(datetime, format_string, locale) View Source 
lformat!(Timex.Convertable.t, format :: String.t, locale :: String.t) ::
  String.t |
  no_return

Same as lformat/3, except local_format! raises on error.

See lformat/3 docs for usage examples.

Link to this function lformat!(datetime, format_string, locale, formatter) View Source 
lformat!(Timex.Convertable.t, format :: String.t, locale :: String.t, formatter :: atom) ::
  String.t |
  no_return

Same as lformat/4, except local_format! raises on error.

See lformat/4 docs for usage examples

Link to this function lformat_duration(timestamp, locale) View Source 
lformat_duration(Timex.Types.timestamp, locale :: String.t) ::
  String.t |
  {:error, term}

Same as format_duration/1, except takes a locale for use in translation

Link to this function lformat_duration(timestamp, locale, formatter) View Source 
lformat_duration(Timex.Types.timestamp, locale :: String.t, atom) ::
  String.t |
  {:error, term}

Same as lformat_duration/2, except takes a formatter as an argument

Link to this function local() View Source 
local ::
  DateTime.t |
  Timex.AmbiguousDateTime.t |
  {:error, term}

Returns a DateTime representing the current moment in time in the local timezone.

Link to this function local(date) View Source 
local(Timex.Types.valid_datetime) ::
  DateTime.t |
  Timex.AmbiguousDateTime.t |
  {:error, term}

Returns a DateTime representing the given date/time in the local timezone

Link to this function month_name(num) View Source 
month_name(Timex.Types.month) ::
  String.t |
  {:error, :invalid_month_number}

Get the name of the month corresponding to the provided number

Examples 

iex> Elixir.Timex.month_name(1)
"January"
iex> Elixir.Timex.month_name(0)
{:error, :invalid_month_number}
Link to this function month_shortname(num) View Source 
month_shortname(Timex.Types.month) ::
  String.t |
  {:error, :invalid_month_number}

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

Examples 

iex> Elixir.Timex.month_shortname(1)
"Jan"
iex> Elixir.Timex.month_shortname(0)
{:error, :invalid_month_number}
Link to this function month_to_num(arg1) View Source 
month_to_num(binary) :: integer | {:error, :invalid_month_name}

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

Examples 

iex> Elixir.Timex.month_to_num("January")
1
iex> Elixir.Timex.month_to_num("january")
1
iex> Elixir.Timex.month_to_num("Jan")
1
iex> Elixir.Timex.month_to_num("jan")
1
iex> Elixir.Timex.month_to_num(:jan)
1
Link to this function normalize(atom, year) View Source 
normalize(:date, {integer, integer, integer}) :: Timex.Types.date
normalize(:time, {integer, integer, integer} | {integer, integer, integer, integer}) :: Timex.Types.time
normalize(:year | :month | :day | :hour | :minute | :second | :millisecond | :microsecond, integer) :: non_neg_integer

Given a unit to normalize, and the value to normalize, produces a valid value for that unit, clamped to whatever boundaries are defined for that unit.

Example 

iex> Timex.normalize(:hour, 26)
23
Link to this function now() View Source 
now() :: DateTime.t

Returns a DateTime representing the current moment in time in UTC

Link to this function now(tz) View Source 
now(Timex.Types.valid_timezone) ::
  DateTime.t |
  Timex.AmbiguousDateTime.t |
  {:error, term}

Returns a DateTime representing the current moment in time in the provided timezone.

Link to this function parse(datetime_string, format_string) View Source 
parse(String.t, String.t) ::
  {:ok, DateTime.t | NaiveDateTime.t} |
  {:error, term}

Parses a datetime string into a DateTime struct, using the provided format string (and optional tokenizer).

See Timex.Format.DateTime.Formatters.Default or Timex.Format.DateTime.Formatters.Strftime for documentation on the syntax supported in format strings by their respective tokenizers.

To use the Default tokenizer, simply call parse/2. To use the Strftime tokenizer, you can either alias and pass Timex.Parse.DateTime.Tokenizer.Strftime by module name, or as a shortcut, you can pass :strftime instead.

Examples 

iex> use Timex
...> {:ok, result} = Timex.parse("2016-02-29", "{YYYY}-{0M}-{D}")
...> result
~N[2016-02-29T00:00:00]

iex> use Timex
...> expected = Timex.to_datetime({{2016, 2, 29}, {22, 25, 0}}, "America/Chicago")
...> {:ok, result} = Timex.parse("2016-02-29T22:25:00-06:00", "{ISO:Extended}")
...> Timex.equal?(expected, result)
true

iex> use Timex
...> expected = Timex.to_datetime({{2016, 2, 29}, {22, 25, 0}}, "America/Chicago")
...> {:ok, result} = Timex.parse("2016-02-29T22:25:00-06:00", "%FT%T%:z", :strftime)
...> Timex.equal?(expected, result)
true
Link to this function parse(datetime_string, format_string, tokenizer) View Source 
parse(String.t, String.t, atom) ::
  {:ok, DateTime.t | NaiveDateTime.t} |
  {:error, term}

See Timex.Parse.DateTime.Parser.parse/3.

Link to this function parse!(datetime_string, format_string) View Source 
parse!(String.t, String.t) ::
  DateTime.t |
  NaiveDateTime.t |
  no_return

Same as parse/2 and parse/3, except parse! raises on error.

See parse/2 or parse/3 docs for usage examples.

Link to this function parse!(datetime_string, format_string, tokenizer) View Source 
parse!(String.t, String.t, atom) ::
  DateTime.t |
  NaiveDateTime.t |
  no_return

See Timex.Parse.DateTime.Parser.parse!/3.

Link to this function quarter(month) View Source 
quarter(Timex.Types.month | Timex.Types.valid_datetime) ::
  1..4 |
  {:error, term}

Returns what quarter of the year the given date/time falls in.

Examples 

iex> Timex.quarter(4)
2
Link to this function set(date, options) View Source 
set(Timex.Types.valid_datetime, set_options) :: Timex.Types.valid_datetime

Return a new date/time value 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.

Options which do not apply to the input value (for example, :hour against a Date struct), will be ignored.

Example 

iex> use Timex
...> expected = ~D[2015-02-28]
...> result = Timex.set(expected, [month: 2, day: 30])
...> result == expected
true

iex> use Timex
...> expected = ~N[2016-02-29T23:30:00]
...> result = Timex.set(expected, [hour: 30])
...> result === expected
true
Link to this function shift(date, options) View Source 
shift(Timex.Types.valid_datetime, shift_options) ::
  Timex.Types.valid_datetime |
  Timex.AmbiguousDateTime.t |
  {:error, term}

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

The result of applying the shift will be the same type as that of the input, with the exception of shifting DateTimes, which may result in an AmbiguousDateTime if the shift moves to an ambiguous time period for the zone of that DateTime.

If an error occurs, an error tuple will be returned.

Examples

Shifting across timezone changes

iex> use Timex
...> datetime = Timex.to_datetime({{2016,3,13}, {1,0,0}}, "America/Chicago")
...> # 2-3 AM doesn't exist
...> shifted = Timex.shift(datetime, hours: 1)
...> {datetime.zone_abbr, shifted.zone_abbr, shifted.hour}
{"CST", "CDT", 3}

Shifting into an ambiguous time period

iex> use Timex
...> datetime = Timex.to_datetime({{1895,12,31}, {0,0,0}}, "Asia/Taipei")
...> %AmbiguousDateTime{} = expected = Timex.to_datetime({{1895,12,31}, {23,55,0}}, "Asia/Taipei")
...> expected == Timex.shift(datetime, hours: 23, minutes: 53, seconds: 120)
true

Shifting and leap days

iex> use Timex
...> date = ~D[2016-02-29]
...> Timex.shift(date, years: -1)
~D[2015-02-28]
Link to this function start(type, args) View Source

Called when an application is started.

This function is called when an the application is started using Application.start/2 (and functions on top of that, such as Application.ensure_started/2). This function should start the top-level process of the application (which should be the top supervisor of the application’s supervision tree if the application follows the OTP design principles around supervision).

start_type defines how the application is started:

  • :normal - used if the startup is a normal startup or if the application is distributed and is started on the current node because of a failover from another mode and the application specification key :start_phases is :undefined.
  • {:takeover, node} - used if the application is distributed and is started on the current node because of a failover on the node node.
  • {:failover, node} - used if the application is distributed and is started on the current node because of a failover on node node, and the application specification key :start_phases is not :undefined.

start_args are the arguments passed to the application in the :mod specification key (e.g., mod: {MyApp, [:my_args]}).

This function should either return {:ok, pid} or {:ok, pid, state} if startup is successful. pid should be the PID of the top supervisor. state can be an arbitrary term, and if omitted will default to []; if the application is later stopped, state is passed to the stop/1 callback (see the documentation for the c:stop/1 callback for more information).

use Application provides no default implementation for the start/2 callback.

Callback implementation for Application.start/2.

Link to this function subtract(date, duration) View Source 
subtract(Timex.Convertable.t, Timex.Types.timestamp) ::
  Timex.Types.valid_datetime |
  Timex.AmbiguousDateTime.t |
  {:error, term}

Subtract time from a date using a Duration Same as shift(date, Duration.from_minutes(5) |> Duration.invert, :timestamp).

Link to this function timezone(tz, datetime) View Source 
timezone(Timex.Types.valid_timezone, Timex.Convertable.t) ::
  Timex.TimezoneInfo.t |
  Timex.AmbiguousTimezoneInfo.t |
  {:error, term}

Get a TimezoneInfo object for the specified offset or name.

When offset or name is invalid, exception is raised.

If no DateTime value is given for the second parameter, the current date/time will be used (in other words, it will return the current timezone info for the given zone). If one is provided, the timezone info returned will be based on the provided DateTime (or Erlang datetime tuple) value.

Examples 

iex> date = Timex.to_datetime({2015, 4, 12})
...> tz = Timex.timezone(:utc, date)
...> tz.full_name
"Etc/UTC"

iex> tz = Timex.timezone("America/Chicago", {2015,4,12})
...> {tz.full_name, tz.abbreviation}
{"America/Chicago", "CDT"}

iex> tz = Elixir.Timex.timezone(+2, {2015, 4, 12})
...> {tz.full_name, tz.abbreviation}
{"Etc/GMT-2", "+02"}
Link to this function timezones() View Source 
timezones() :: [String.t]

Returns a list of all valid timezone names in the Olson database

Link to this function to_date(date) View Source 
to_date(Timex.Types.calendar_types | Timex.Types.date | Timex.Types.datetime) :: Date.t
to_date(Timex.Types.valid_datetime) ::
  Timex.Types.date |
  Timex.Types.datetime

Convert a date/time value to a Date struct.

Link to this function to_datetime(from) View Source 
to_datetime(Timex.Types.calendar_types | Timex.Types.date | Timex.Types.datetime) ::
  DateTime.t |
  {:error, term}

Convert a date/time value and timezone name to a DateTime struct. If the DateTime is ambiguous and cannot be resolved, an AmbiguousDateTime will be returned, allowing the developer to choose which of the two choices is desired.

If no timezone is provided, “Etc/UTC” will be used

Link to this function to_datetime(from, timezone) View Source 
to_datetime(Timex.Types.calendar_types | Timex.Types.date | Timex.Types.datetime, Timex.Types.valid_timezone) ::
  DateTime.t |
  Timex.AmbiguousDateTime.t |
  {:error, term}

See Timex.Protocol.to_datetime/2.

Link to this function to_erl(date) View Source

Convert a date/time value to it’s Erlang representation

Link to this function to_gregorian_microseconds(datetime) View Source 
to_gregorian_microseconds(Timex.Types.valid_datetime) ::
  non_neg_integer |
  {:error, term}

Convert a date/time value to gregorian microseconds (microseconds since start of year zero)

Link to this function to_gregorian_seconds(datetime) View Source 
to_gregorian_seconds(Timex.Types.valid_datetime) ::
  non_neg_integer |
  {:error, term}

Convert a date/time value to gregorian seconds (seconds since start of year zero)

Link to this function to_julian(datetime) View Source 
to_julian(Timex.Types.valid_datetime) :: integer

Convert a date/time value to a Julian calendar date number

Link to this function to_naive_datetime(date) View Source 
to_naive_datetime(Timex.Types.calendar_types | Timex.Types.date | Timex.Types.datetime) :: NaiveDateTime.t

Convert a date/time value to a NaiveDateTime struct.

Link to this function to_unix(datetime) View Source 
to_unix(Timex.Types.valid_datetime) ::
  non_neg_integer |
  {:error, term}

Convert a date/time value to seconds since the UNIX epoch

Link to this function today() View Source 
today() :: Date.t

Returns a Date representing the current day in UTC

Link to this function validate_format(format_string) View Source 
validate_format(String.t) :: :ok | {:error, term}

Given a format string, validates that the format string is valid for the Default formatter.

Given a format string and a formatter, validates that the format string is valid for that formatter.

Examples 

iex> use Timex
...> Timex.validate_format("{YYYY}-{M}-{D}")
:ok

iex> use Timex
...> Timex.validate_format("{YYYY}-{M}-{V}")
{:error, "Expected end of input at line 1, column 11"}

iex> use Timex
...> Timex.validate_format("%FT%T%:z", :strftime)
:ok
Link to this function validate_format(format_string, formatter) View Source 
validate_format(String.t, atom) :: :ok | {:error, term}

See Timex.Format.DateTime.Formatter.validate/2.

Link to this function week_of_month(datetime) View Source 
week_of_month(Timex.Types.valid_datetime) :: Timex.Types.week_of_month

Given a Convertable, this function returns the week number of the date provided, starting at 1.

Examples 

iex> Timex.week_of_month(~D[2016-03-05])
1

iex> Timex.week_of_month(~N[2016-03-14T00:00:00Z])
3
Link to this function week_of_month(year, month, day) View Source 
week_of_month(Timex.Types.year, Timex.Types.month, Timex.Types.day) :: Timex.Types.week_of_month

Same as week_of_month/1, except takes year, month, and day as distinct arguments

Examples 

iex> Timex.week_of_month(2016, 3, 30)
5
Link to this function weekday(datetime) View Source 
weekday(Timex.Types.valid_datetime) ::
  Timex.Types.weekday |
  {:error, term}

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

Examples 

iex> Timex.epoch |> Elixir.Timex.weekday
4 # (i.e. Thursday)
Link to this function zero() View Source 
zero() :: Date.t

Returns a Date representing the start of the Gregorian epoch