README.md
1## Timex
2
3[](https://travis-ci.org/bitwalker/timex)
4[](https://hex.pm/packages/timex)
5[](https://inch-ci.org/github/bitwalker/timex)
6[](https://coveralls.io/github/bitwalker/timex?branch=master)
7
8Timex is a rich, comprehensive Date/Time library for Elixir projects, with full timezone support via the `:tzdata` package. If
9you need to manipulate dates, times, datetimes, timestamps, etc., then Timex is for you! It is very easy to use Timex types
10in place of default Erlang types, as well as Ecto types via the `timex_ecto` package.
11
12The complete documentation for Timex is located [here](https://hexdocs.pm/timex).
13
14## Migrating to Timex 3.x
15
16See the Migrating section further down for details. If you are migrating from earlier than 2.x,
17please review [this migration doc for 1.x to 2.x](https://github.com/bitwalker/timex/tree/2.2.1#migrating).
18
19Timex 3.0 is a significant rewrite, in order to accommodate Elixir 1.3's new Calendar types in a semantically
20correct way. The external API is mostly the same, but there are changes, many without deprecations, so please
21read the changelog carefully.
22
23## Getting Started
24
25There are some brief examples on usage below, but I highly recommend you review the
26API docs [here](https://hexdocs.pm/timex), there are many examples, and some extra pages with
27richer documentation on specific subjects such as custom formatters/parsers, etc.
28
29### Adding Timex To Your Project
30
31To use Timex with your projects, edit your `mix.exs` file and add it as a dependency:
32
33```elixir
34defp deps do
35 [{:timex, "~> 3.1"}]
36end
37
38defp application do
39 [applications: [:timex]]
40end
41```
42
43### Quickfast introduction
44
45To use Timex, I recommend you add `use Timex` to the top of the module where you will be working with Timex modules,
46all it does is alias common types so you can work with them more comfortably. If you want to see the specific aliases
47added, check the top of the `Timex` module, in the `__using__/1` macro definition.
48
49Here's a few simple examples:
50
51```elixir
52> use Timex
53> Timex.today
54~D[2016-02-29]
55
56> datetime = Timex.now
57#<DateTime(2016-02-29T12:30:30.120+00:00Z Etc/UTC)
58
59> Timex.now("America/Chicago")
60#<DateTime(2016-02-29T06:30:30.120-06:00 America/Chicago)
61
62> Duration.now
63#<Duration(P46Y6M24DT21H57M33.977711S)>
64
65> {:ok, default_str} = Timex.format(datetime, "{ISO:Extended}")
66{:ok, "2016-02-29T12:30:30.120+00:00"}
67
68> {:ok, relative_str} = Timex.shift(datetime, minutes: -3) |> Timex.format("{relative}", :relative)
69{:ok, "3 minutes ago"}
70
71> strftime_str = Timex.format!(datetime, "%FT%T%:z", :strftime)
72"2016-02-29T12:30:30+00:00"
73
74> Timex.parse(strftime_str, "{ISO:Extended}")
75{:ok, #<DateTime(2016-02-29T12:30:30.120+00:00 Etc/Utc)}
76
77> Timex.parse!(strftime_str, "%FT%T%:z", :strftime)
78#<DateTime(2016-02-29T12:30:30.120+00:00 Etc/Utc)
79
80> Duration.diff(Duration.now, Duration.zero, :days)
8116850
82
83> Timex.shift(date, days: 3)
84~D[2016-03-03]
85
86> Timex.shift(datetime, hours: 2, minutes: 13)
87#<DateTime(2016-02-29T14:43:30.120Z Etc/UTC)>
88
89> timezone = Timezone.get("America/Chicago", Timex.now)
90#<TimezoneInfo(America/Chicago - CDT (-06:00:00))>
91
92> Timezone.convert(datetime, timezone)
93#<DateTime(2016-02-29T06:30:30.120-06:00 America/Chicago)>
94
95> Timex.before?(Timex.today, Timex.shift(Timex.today, days: 1))
96true
97
98> Timex.before?(Timex.shift(Timex.today, days: 1), Timex.today)
99false
100
101> interval = Timex.Interval.new(from: ~D[2016-03-03], until: [days: 3])
102%Timex.Interval{from: ~N[2016-03-03 00:00:00], left_open: false,
103 right_open: true, step: [days: 1], until: ~N[2016-03-06 00:00:00]}
104
105> ~D[2016-03-04] in interval
106true
107
108> ~N[2016-03-04 00:00:00] in interval
109true
110
111> ~N[2016-03-02 00:00:00] in interval
112false
113
114> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-04], until: [days: 1]), interval)
115true
116
117> Timex.Interval.overlaps?(Timex.Interval.new(from: ~D[2016-03-07], until: [days: 1]), interval)
118false
119
120```
121
122There 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`)
123
124## Extensibility
125
126Timex exposes a number of extension points for you, in order to accommodate different use cases:
127
128Timex 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.
129
130Timex also defines a `Timex.Comparable` protocol, which you can extend to add comparisons to custom date/datetime types.
131
132You 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.
133
134## Common Issues
135
136### `iso_*` Functions
137
138Timex 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!
139
140### Timex with escript
141
142If 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.
143
144### Automatic time zone updates
145
146Timex includes the [Tzdata](https://github.com/lau/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](https://github.com/lau/tzdata#automatic-data-updates) for details.
147
148## Migrating
149
150If 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.
151
152### Overview of 3.x changes
153
154Please see the `CHANGELOG.md` file for the list of all changes made, below are a brief recap of the major points, and
155instructions on how to migrate your existing Timex-based code to 3.x.
156
157- 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.
158- All Timex-provided types have been removed, with the exception of `Time` which has been renamed to `Duration` to better fit it's purpose,
159`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.
160- 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).
161
162A variety of improvements came about as well:
163
164- Microsecond precision everywhere it can be maintained
165- Various bug fixes from the 2.x release which were held back
166- A lot of code clean up
167- Faster compilation
168- Fixed typespecs, docs, and tests across the board
169- Added Julian calendar support
170
171
172## Roadmap
173
174The following are an unordered list of things I plan for Timex in the future, if you
175have specific requests, please open an issue with "RFC" in the title, and we can discuss
176it, and hopefully get input from the community.
177
178- 100% test coverage (well under way!)
179- QuickCheck tests (haven't started this, but I really want to start ASAP)
180- `{ASP.NET}` formatting/parsing token for interop with .NET services (probably in the next release)
181- Relative time formatter/parser, along the lines of Moment.js's `fromNow`, `toNow`, `timeTo`, and `timeFrom` formatting functions.
182- Calendar time formatter/parser, along the lines of Moment.js's calendar time formatter
183- Recurring dates/times API
184
185## License
186
187This software is licensed under [the MIT license](LICENSE.md).
188
){kind=link}
){kind=link}
){kind=link}
){kind=link}