UTC DateTime

UTC DateTime

Hex.pm Build Status Coverage Status Hex.pm

A datetime implementation constraint to UTC.

Goal

The goal is to create datetime type, which unlike DateTime guarantees to be UTC only, without ignoring the existence of timezones like a NaiveDateTime.

A secondary goal is to be more efficient or at least on par with the build in datetimes. (DateTime, NaiveDateTime) In practice the goal is to use less memory and perform common [shared] actions faster.

Quick Setup 

iex> UTCDateTime.utc_now
~Z[2019-12-14 16:08:13.042407]

iex> UTCDateTime.from_rfc3339!("2019-12-14T16:08:13.042407+01:00")
~Z[2019-12-14 15:08:13.042407]

iex> UTCDateTime.from_iso8601!("2019-12-14 16:08:13.042407")
~Z[2019-12-14 16:08:13.042407]

Installation

The package can be installed by adding utc_datetime to your list of dependencies in mix.exs:

def deps do
  [
    {:utc_datetime, "~> 1.0"}
  ]
end

The docs can be found at https://hexdocs.pm/utc_datetime.

Integration

Ecto

Hex.pm

Integrates with Ecto as a timestamp type.

Example:

defmodule User do
  use Ecto.Schema
  @timestamps_opts [type: UTCDateTime]

  schema "users" do
    field :name, :string
    timestamps()
  end
...

or alternatively

  schema "users" do
    field :name, :string
    timestamps(type: UTCDateTime)
  end

The UTCDateTime.USec is also available and will hold microsecond precision timestamps.

Fixtures

Hex.pm

Integrates with Fixtures and supplies random UTC timestamps for testing and development.

Example:

iex> Fixtures.Time.timestamp
~Z[1982-03-25 05:35:07]

Jason

Hex.pm

Integrates with Jason and supports out of the box encoding almost twice as fast as the build in DateTime and NaiveDateTime.

Example:

iex> Jason.encode!(%{created_at: ~Z[2019-12-16 00:00:12.068421]})
"{\"created_at\":\"2019-12-16T00:00:12.068421Z\"}"

TimeMachinex

Hex.pm

Integrates with TimeMachinex and can be used through TimeMachinex.utc_now/1.

Example:

iex> TimeMachinex.utc_now
~Z[2019-12-16 00:00:12.068421]

Changelog

v1.0.0 (2020-03-15)

First actual release.

Adds Elixir 1.10 support.

v0.0.13 (2020-01-13)

Fixes:

  • Ecto type improve dump in case it is already a DateTime.

v0.0.12 (2020-01-08)

Fixes:

  • Ecto conditional compile fix.

v0.0.11 (2020-01-07)

Fixes:

v0.0.10 (2020-01-06)

New Features:

v0.0.9 (2019-12-20)

New Features:

  • from_unix/1, from_unix/2
  • to_epoch/2, to_epoch/3
  • to_ntfs/1, to_ntfs/2
  • to_unix/1, to_unix/2

v0.0.8 (2019-12-20)

New Features:

  • add/2, add/3
  • diff/2, diff3

Fixes:

  • Allow negative years in ISO 8601.

Cleanup:

  • truncate/2

v0.0.7 (2019-12-16)

New Features:

  • truncate/2

v0.0.6 (2019-12-15)

New Features:

  • Jason [encoding] integration.

v0.0.5 (2019-12-15)

New Features:

  • Ecto type integration.

v0.0.4 (2019-12-15)

New Features:

  • compare/2
  • from_date/2
  • from_erl/2, from_erl!/2
  • to_date/2
  • to_erl/1
  • to_time/2

v0.0.3 (2019-12-15)

New Features:

  • Epochs

v0.0.2 (2019-12-15)

New Features:

v0.0.1 (2019-12-14)

Base UTCDateTime.

New Features:

  • from_datetime/1
  • from_naive/1
  • to_datetime/1, to_datetime/2
  • to_naive/1, to_naive/2
  • utc_now/0

Experimental:

Additional:

  • Benchmarks
  • Roadmap

Roadmap

  • Integrations

    • :fixtures

  • Release 0.0.14

    • to_local_datetime/1 (in caller)

  • Release 0.0.15

    • from_human/1 best effort parse

Copyright (c) 2019, Ian Luites.

UTCDateTime code is licensed under the MIT License.