# `Ecto.DateTimeRange.UTCDateTime`
[🔗](https://github.com/synchronal/ecto_date_time_range/blob/main/lib/ecto/date_time_range/utc_date_time.ex#L1)

An `Ecto.Type` wrapping a `:tstzrange` Postgres column. To the application, it appears as
a struct with `:start_at` and `:end_at`, with `:utc_datetime` values.

```
defmodule Core.Thing do
  use Ecto.Schema
  import Ecto.Changeset

  schema "things" do
    field :performed_during, Ecto.DateTimeRange.UTCDateTime
  end

  @required_attrs ~w[performed_during]a
  def changeset(data \ %__MODULE__{}, attrs) do
    data
    |> cast(attrs, @required_attrs)
    |> validate_required(@required_attrs)
  end
end
```

# `cast`

Converts user-provided data (for example from a form) to the Elixir term.

# `dump`

Converts the Elixir term to the Ecto native type.

# `embed_as`

Declares than when used in embedded schemas, the type will be dumped before being encoded.

# `equal?`

Checks if two terms are equal.

# `load`

Converts the Ecto native type to the Elixir term.

# `type`

Declares the native type that will be used in the database.

# `t`

```elixir
@type t() :: %Ecto.DateTimeRange.UTCDateTime{
  end_at: DateTime.t(),
  start_at: DateTime.t()
}
```

# `contains?`

```elixir
@spec contains?(t(), DateTime.t()) :: boolean()
```

Returns true or false depending on whether the time is falls within the
specified range.

## Example

```
iex> import Ecto.DateTimeRange
iex> range = ~t[2020-01-01T01:00:00Z..2020-01-02T01:00:00Z]U
...>
iex> Ecto.DateTimeRange.UTCDateTime.contains?(range, ~U[2020-01-01T00:59:59Z])
false
iex> Ecto.DateTimeRange.UTCDateTime.contains?(range, ~U[2020-01-01T01:00:00Z])
true
iex> Ecto.DateTimeRange.UTCDateTime.contains?(range, ~U[2020-01-02T00:59:59Z])
true
iex> Ecto.DateTimeRange.UTCDateTime.contains?(range, ~U[2020-01-02T01:00:00Z])
false
iex> Ecto.DateTimeRange.UTCDateTime.contains?(range, ~U[2020-01-03T01:00:00Z])
false
```

# `parse`

```elixir
@spec parse(binary()) :: {:ok, t()} | {:error, term()}
```

Create an `Ecto.DateTimeRange.UTCDateTime` from two ISO8601 strings.

## Example

```
iex> Ecto.DateTimeRange.UTCDateTime.parse("2020-02-02T00:01:00Z..2020-02-02T00:01:01Z")
{:ok, %Ecto.DateTimeRange.UTCDateTime{start_at: ~U[2020-02-02T00:01:00Z], end_at: ~U[2020-02-02T00:01:01Z]}}

iex> Ecto.DateTimeRange.UTCDateTime.parse("2020-02-02T00:01:00Z..later")
{:error, "Unable to parse DateTime(s) from input"}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*