timex

## Timex

[![Main](https://github.com/bitwalker/timex/workflows/elixir/badge.svg?branch=main)](https://github.com/bitwalker/timex/actions?query=workflow%3A%22elixir%22+branch%3Amain)
[![Hex.pm Version](https://img.shields.io/hexpm/v/timex.svg?style=flat)](https://hex.pm/packages/timex)
[![Coverage Status](https://coveralls.io/repos/github/bitwalker/timex/badge.svg?branch=main)](https://coveralls.io/github/bitwalker/timex?branch=main)

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](https://hexdocs.pm/timex).

## Requirements

Timex requires Elixir 1.16 or later and Erlang/OTP 26 or later.

Timezone updates use tzdata's built-in HTTP client, which verifies HTTPS against
the operating system's trusted CA certificates. Ensure your deployment includes
an accessible CA certificate bundle. Timex no longer requires Hackney or its
dependencies.

When upgrading, remove an explicit `config :tzdata, :http_client,
Tzdata.HTTPClient.Hackney` setting to use the built-in client. If your application
still needs Hackney independently, update it to a patched version and audit the
whole application's dependency graph with `mix hex.audit`. Updating Timex does not
upgrade unrelated application dependencies automatically.

## Supported calendars and years

Timex's date arithmetic and conversion entrypoints accept `Date`,
`NaiveDateTime`, and `DateTime` inputs in `Calendar.ISO`, with years from 0
through 9999. Date tuples and maps use the same year range. Unsupported inputs
return `{:error, {:unsupported_calendar, calendar}}` or
`{:error, {:unsupported_year, year}}`; `is_valid?/1` returns `false`, and
boolean comparison helpers such as `equal?/2` raise `ArgumentError`.
Comparisons also require the UTC instant to fall within that year range.
ISO week-year metadata may refer to the preceding year: for example,
`Timex.iso_week(~D[0000-01-01])` returns `{-1, 52}`.

For another calendar, explicitly convert with `Date.convert/2`,
`NaiveDateTime.convert/2`, or `DateTime.convert/2` and `Calendar.ISO` before
calling Timex. These conversions preserve the represented date or instant
instead of reinterpreting another calendar's fields as ISO values.

Setters retain their normalization policy: negative replacement years clamp
to zero, while years above 9999 return an unsupported-year error. Using
`validate: false` permits raw replacement fields outside this range; subsequent
Timex operations still require supported inputs. Composite date/time setter
options must use `Calendar.ISO` even when validation is disabled.

These checks apply to Timex's protocol-backed arithmetic and conversions.
Standard-library constructor delegates such as `from_uni