defmodule Ecto.Type do
@moduledoc """
Defines functions and the `Ecto.Type` behaviour for implementing
basic custom types.
Ecto provides two types of custom types: basic types and
parameterized types. Basic types are simple, requiring only four
callbacks to be implemented, and are enough for most occasions.
Parameterized types can be customized on the field definition and
provide a wide variety of callbacks.
The definition of basic custom types and all of their callbacks are
available in this module. You can learn more about parameterized
types in `Ecto.ParameterizedType`. If in doubt, prefer to use
basic custom types and rely on parameterized types if you need
the extra functionality.
## Example
Imagine you want to store a URI struct as part of a schema in a
url-shortening service. There isn't an Ecto field type to support
that value at runtime therefore a custom one is needed.
You also want to query not only by the full url, but for example
by specific ports used. This is possible by putting the URI data
into a map field instead of just storing the plain
string representation.
from s in ShortUrl,
where: fragment("?->>? ILIKE ?", s.original_url, "port", "443")
So the custom type does need to handle the conversion from
external data to runtime data (`c:cast/1`) as well as
transforming that runtime data into the `:map` Ecto native type and
back (`c:dump/1` and `c:load/1`).
defmodule EctoURI do
use Ecto.Type
def type, do: :map
# Provide custom casting rules.
# Cast strings into the URI struct to be used at runtime
def cast(uri) when is_binary(uri) do
{:ok, URI.parse(uri)}
end
# Accept casting of URI structs as well
def cast(%URI{} = uri), do: {:ok, uri}
# Everything else is a failure though
def cast(_), do: :error
# When loading data from the database, as long as it's a map,
# we just put the data back into a URI struct to be stored in
# the loaded schema struct.
def load(data) when is_map(data) do
data =
for {key, val} <- data do
{String.to_existing_atom(key), val}
end
{:ok, struct!(URI, data)}
end
# When dumping data to the database, we *expect* a URI struct
# but any value could be inserted into the schema struct at runtime,
# so we need to guard against them.
def dump(%URI{} = uri), do: {:ok, Map.from_struct(uri)}
def dump(_), do: :error
end
Now we can use our new field type above in our schemas:
defmodule ShortUrl do
use Ecto.Schema
schema "posts" do
field :original_url, EctoURI
end
end
Note: `nil` values are always bypassed and cannot be handled by
custom types.
> #### `use Ecto.Type` {: .info}
>
> When you `use Ecto.Type`, it will set `@behaviour Ecto.Type` and define
> default, overridable implementations for `c:embed_as/1` and `c:equal?/2`.
## Custom types and primary keys
Remember that, if you change the type of your primary keys,
you will also need to change the type of all associations that
point to said primary key.
Imagine you want to encode the ID so they cannot enumerate the
content in your application. An Ecto type could handle the conversion
between the encoded version of the id and its representation in the
database. For the sake of simplicity, we'll use base64 encoding in
this example:
defmodule EncodedId do
use Ecto.Type
def type, do: :id
def cast(id) when is_integer(id) do
{:ok, encode_id(id)}
end
def cast(_), do: :error
def dump(id) when is_binary(id) do
{:ok, id_decoded} = Base.decode64(id)
{:ok, String.to_integer(id_decoded)}
end
def load(id) when is_integer(id) do
{:ok, encode_id(id)}
end
defp encode_id(id) do
id
|> Integer.to_string()
|> Base.encode64()
end
end
To use it as the type for the id in our schema, we can use the
`@primary_key` module attribute:
defmodule BlogPost do
use Ecto.Schema
@primary_key {:id, EncodedId, autogenerate: true}
schema "posts" do
belongs_to :author, Author, type: EncodedId
field :content, :string
end
end
defmodule Author do
use Ecto.Schema
@primary_key {:id, EncodedId, autogenerate: true}
schema "authors" do
field :name, :string
has_many :posts, BlogPost
end
end
The `@primary_key` attribute will tell ecto which type to
use for the id.
Note the `type: EncodedId` option given to `belongs_to` in
the `BlogPost` schema. By default, Ecto will treat
associations as if their keys were `:integer`s. Our primary
keys are a custom type, so when Ecto tries to cast those
ids, it will fail.
Alternatively, you can set `@foreign_key_type EncodedId`
after `@primary_key` to automatically configure the type
of all `belongs_to` fields.
"""
import Kernel, except: [match?: 2]
@doc false
defmacro __using__(_opts) do
quote location: :keep do
@behaviour Ecto.Type
def embed_as(_), do: :self
def equal?(term1, term2), do: term1 == term2
defoverridable [embed_as: 1, equal?: 2]
end
end
@typedoc "An Ecto type, primitive or custom."
@type t :: primitive | custom
@typedoc "Primitive Ecto types (handled by Ecto)."
@type primitive :: base | composite
@typedoc "Custom types are represented by user-defined modules."
@type custom :: module | {:parameterized, module, term}
@type base :: :integer | :float | :boolean | :string | :map |
:binary | :decimal | :id | :binary_id |
:utc_datetime | :naive_datetime | :date | :time | :any |
:utc_datetime_usec | :naive_datetime_usec | :time_usec
@type composite :: {:array, t} | {:map, t} | private_composite
@typep private_composite :: {:maybe, t} | {:in, t} | {:param, :any_datetime}
@base ~w(
integer float decimal boolean string map binary id binary_id any
utc_datetime naive_datetime date time
utc_datetime_usec naive_datetime_usec time_usec
)a
@composite ~w(array map maybe in param)a
@doc """
Returns the underlying schema type for the custom type.
For example, if you want to provide your own date
structures, the type function should return `:date`.
Note this function is not required to return Ecto primitive
types, the type is only required to be known by the adapter.
"""
@callback type :: t
@doc """
Casts the given input to the custom type.
This callback is called on external input and can return any type,
as long as the `dump/1` function is able to convert the returned
value into an Ecto native type. There are two situations where
this callback is called:
1. When casting values by `Ecto.Changeset`
2. When passing arguments to `Ecto.Query`
You can return `:error` if the given term cannot be cast.
A default error message of "is invalid" will be added to the
changeset.
You may also return `{:error, keyword()}` to customize the
changeset error message and its metadata. Passing a `:message`
key, will override the default message. It is not possible to
override the `:type` key.
For `{:array, CustomType}` or `{:map, CustomType}` the returned
keyword list will be erased and the default error will be shown.
"""
@callback cast(term) :: {:ok, term} | :error | {:error, keyword()}
@doc """
Loads the given term into a custom type.
This callback is called when loading data from the database and
receives an Ecto native type. It can return any type, as long as
the `dump/1` function is able to convert the returned value back
into an Ecto native type.
"""
@callback load(term) :: {:ok, term} | :error
@doc """
Dumps the given term into an Ecto native type.
This callback is called with any term that was stored in the struct
and it needs to validate them and convert it to an Ecto native type.
"""
@callback dump(term) :: {:ok, term} | :error
@doc """
Checks if two terms are semantically equal.
This callback is used for determining equality of types in
`Ecto.Changeset`.
"""
@callback equal?(term, term) :: boolean
@doc """
Dictates how the type should be treated inside embeds.
By default, the type is sent as itself, without calling
dumping to keep the higher level representation. But
it can be set to `:dump` so that it is dumped before
being encoded.
"""
@callback embed_as(format :: atom) :: :self | :dump
@doc """
Generates a loaded version of the data.
This is callback is invoked when a custom type is given
to `field` with the `:autogenerate` flag.
"""
@callback autogenerate() :: term()
@optional_callbacks autogenerate: 0
## Functions
@doc """
Checks if we have a primitive type.
iex> primitive?(:string)
true
iex> primitive?(Another)
false
iex> primitive?({:array, :string})
true
iex> primitive?({:array, Another})
true
"""
@spec primitive?(t) :: boolean
def primitive?({:parameterized, _, _}), do: true
def primitive?({composite, _}) when composite in @composite, do: true
def primitive?(base) when base in @base, do: true
def primitive?(_), do: false
@doc """
Checks if the given atom can be used as composite type.
iex> composite?(:array)
true
iex> composite?(:string)
false
"""
@spec composite?(atom) :: boolean
def composite?(atom), do: atom in @composite
@doc """
Checks if the given atom can be used as base type.
iex> base?(:string)
true
iex> base?(:array)
false
iex> base?(Custom)
false
"""
@spec base?(atom) :: boolean
def base?(atom), do: atom in @base
@doc """
Gets how the type is treated inside embeds for the given format.
See `c:embed_as/1`.
"""
def embed_as({:parameterized, module, params}, format), do: module.embed_as(format, params)
def embed_as({composite, type}, format) when composite in @composite, do: embed_as(type, format)
def embed_as(base, _format) when base in @base, do: :self
def embed_as(mod, format), do: mod.embed_as(format)
@doc """
Dumps the `value` for `type` considering it will be embedded in `format`.
## Examples
iex> Ecto.Type.embedded_dump(:decimal, Decimal.new("1"), :json)
{:ok, Decimal.new("1")}
"""
def embedded_dump(type, value, format) do
case embed_as(type, format) do
:self -> {:ok, value}
:dump -> dump(type, value, &embedded_dump(&1, &2, format))
end
end
@doc """
Loads the `value` for `type` considering it was embedded in `format`.
## Examples
iex> Ecto.Type.embedded_load(:decimal, "1", :json)
{:ok, Decimal.new("1")}
"""
def embedded_load(type, value, format) do
case embed_as(type, format) do
:self ->
case cast(type, value) do
{:ok, _} = ok -> ok
_ -> :error
end
:dump ->
load(type, value, &embedded_load(&1, &2, format))
end
end
@doc """
Retrieves the underlying schema type for the given, possibly custom, type.
iex> type(:string)
:string
iex> type(Ecto.UUID)
:uuid
iex> type({:array, :string})
{:array, :string}
iex> type({:array, Ecto.UUID})
{:array, :uuid}
iex> type({:map, Ecto.UUID})
{:map, :uuid}
"""
@spec type(t) :: t
def type(type)
def type({:parameterized, type, params}), do: type.type(params)
def type({:array, type}), do: {:array, type(type)}
def type({:map, type}), do: {:map, type(type)}
def type(type) when type in @base, do: type
def type(type) when is_atom(type), do: type.type()
def type(type), do: type
@doc """
Checks if a given type matches with a primitive type
that can be found in queries.
iex> match?(:string, :any)
true
iex> match?(:any, :string)
true
iex> match?(:string, :string)
true
iex> match?({:array, :string}, {:array, :any})
true
iex> match?(Ecto.UUID, :uuid)
true
iex> match?(Ecto.UUID, :string)
false
"""
@spec match?(t, primitive) :: boolean
def match?(schema_type, query_type) do
if primitive?(schema_type) do
do_match?(schema_type, query_type)
else
do_match?(schema_type.type, query_type)
end
end
defp do_match?(_left, :any), do: true
defp do_match?(:any, _right), do: true
defp do_match?({outer, left}, {outer, right}), do: match?(left, right)
defp do_match?(:decimal, type) when type in [:float, :integer], do: true
defp do_match?(:binary_id, :binary), do: true
defp do_match?(:id, :integer), do: true
defp do_match?(type, type), do: true
defp do_match?(:naive_datetime, {:param, :any_datetime}), do: true
defp do_match?(:naive_datetime_usec, {:param, :any_datetime}), do: true
defp do_match?(:utc_datetime, {:param, :any_datetime}), do: true
defp do_match?(:utc_datetime_usec, {:param, :any_datetime}), do: true
defp do_match?(_, _), do: false
@doc """
Dumps a value to the given type.
Opposite to casting, dumping requires the returned value
to be a valid Ecto type, as it will be sent to the
underlying data store.
iex> dump(:string, nil)
{:ok, nil}
iex> dump(:string, "foo")
{:ok, "foo"}
iex> dump(:integer, 1)
{:ok, 1}
iex> dump(:integer, "10")
:error
iex> dump(:binary, "foo")
{:ok, "foo"}
iex> dump(:binary, 1)
:error
iex> dump({:array, :integer}, [1, 2, 3])
{:ok, [1, 2, 3]}
iex> dump({:array, :integer}, [1, "2", 3])
:error
iex> dump({:array, :binary}, ["1", "2", "3"])
{:ok, ["1", "2", "3"]}
"""
@spec dump(t, term) :: {:ok, term} | :error
@spec dump(t, term, (t, term -> {:ok, term} | :error)) :: {:ok, term} | :error
def dump(type, value, dumper \\ &dump/2)
def dump({:parameterized, module, params}, value, dumper) do
module.dump(value, dumper, params)
end
def dump(_type, nil, _dumper) do
{:ok, nil}
end
def dump({:maybe, type}, value, dumper) do
case dump(type, value, dumper) do
{:ok, _} = ok -> ok
:error -> {:ok, value}
end
end
def dump({:in, type}, value, dumper) do
case dump({:array, type}, value, dumper) do
{:ok, value} -> {:ok, {:in, value}}
:error -> :error
end
end
def dump({:array, {_, _, _} = type}, value, dumper), do: array(value, type, dumper, false, [])
def dump({:array, type}, value, dumper), do: array(value, type, dumper, true, [])
def dump({:map, type}, value, dumper), do: map(value, type, dumper, false, %{})
def dump(:any, value, _dumper), do: {:ok, value}
def dump(:integer, value, _dumper), do: same_integer(value)
def dump(:float, value, _dumper), do: dump_float(value)
def dump(:boolean, value, _dumper), do: same_boolean(value)
def dump(:map, value, _dumper), do: same_map(value)
def dump(:string, value, _dumper), do: same_binary(value)
def dump(:binary, value, _dumper), do: same_binary(value)
def dump(:id, value, _dumper), do: same_integer(value)
def dump(:binary_id, value, _dumper), do: same_binary(value)
def dump(:decimal, value, _dumper), do: same_decimal(value)
def dump(:date, value, _dumper), do: same_date(value)
def dump(:time, value, _dumper), do: dump_time(value)
def dump(:time_usec, value, _dumper), do: dump_time_usec(value)
def dump(:naive_datetime, value, _dumper), do: dump_naive_datetime(value)
def dump(:naive_datetime_usec, value, _dumper), do: dump_naive_datetime_usec(value)
def dump(:utc_datetime, value, _dumper), do: dump_utc_datetime(value)
def dump(:utc_datetime_usec, value, _dumper), do: dump_utc_datetime_usec(value)
def dump({:param, :any_datetime}, value, _dumper), do: dump_any_datetime(value)
def dump(mod, value, _dumper) when is_atom(mod), do: mod.dump(value)
defp dump_float(term) when is_float(term), do: {:ok, term}
defp dump_float(_), do: :error
defp dump_time(%Time{} = term), do: {:ok, check_no_usec!(term, :time)}
defp dump_time(_), do: :error
defp dump_time_usec(%Time{} = term), do: {:ok, check_usec!(term, :time_usec)}
defp dump_time_usec(_), do: :error
defp dump_any_datetime(%NaiveDateTime{} = term), do: {:ok, term}
defp dump_any_datetime(%DateTime{} = term), do: {:ok, term}
defp dump_any_datetime(_), do: :error
defp dump_naive_datetime(%NaiveDateTime{} = term), do:
{:ok, check_no_usec!(term, :naive_datetime)}
defp dump_naive_datetime(_), do: :error
defp dump_naive_datetime_usec(%NaiveDateTime{} = term),
do: {:ok, check_usec!(term, :naive_datetime_usec)}
defp dump_naive_datetime_usec(_), do: :error
defp dump_utc_datetime(%DateTime{} = datetime) do
kind = :utc_datetime
{:ok, datetime |> check_utc_timezone!(kind) |> check_no_usec!(kind)}
end
defp dump_utc_datetime(_), do: :error
defp dump_utc_datetime_usec(%DateTime{} = datetime) do
kind = :utc_datetime_usec
{:ok, datetime |> check_utc_timezone!(kind) |> check_usec!(kind)}
end
defp dump_utc_datetime_usec(_), do: :error
@doc """
Loads a value with the given type.
iex> load(:string, nil)
{:ok, nil}
iex> load(:string, "foo")
{:ok, "foo"}
iex> load(:integer, 1)
{:ok, 1}
iex> load(:integer, "10")
:error
"""
@spec load(t, term) :: {:ok, term} | :error
@spec load(t, term, (t, term -> {:ok, term} | :error)) :: {:ok, term} | :error
def load(type, value, loader \\ &load/2)
def load({:parameterized, module, params}, value, loader) do
module.load(value, loader, params)
end
def load(_type, nil, _loader) do
{:ok, nil}
end
def load({:maybe, type}, value, loader) do
case load(type, value, loader) do
{:ok, _} = ok -> ok
:error -> {:ok, value}
end
end
def load({:array, {_, _, _} = type}, value, loader), do: array(value, type, loader, false, [])
def load({:array, type}, value, loader), do: array(value, type, loader, true, [])
def load({:map, type}, value, loader), do: map(value, type, loader, false, %{})
def load(:any, value, _loader), do: {:ok, value}
def load(:integer, value, _loader), do: same_integer(value)
def load(:float, value, _loader), do: load_float(value)
def load(:boolean, value, _loader), do: same_boolean(value)
def load(:map, value, _loader), do: same_map(value)
def load(:string, value, _loader), do: same_binary(value)
def load(:binary, value, _loader), do: same_binary(value)
def load(:id, value, _loader), do: same_integer(value)
def load(:binary_id, value, _loader), do: same_binary(value)
def load(:decimal, value, _loader), do: same_decimal(value)
def load(:date, value, _loader), do: same_date(value)
def load(:time, value, _loader), do: load_time(value)
def load(:time_usec, value, _loader), do: load_time_usec(value)
def load(:naive_datetime, value, _loader), do: load_naive_datetime(value)
def load(:naive_datetime_usec, value, _loader), do: load_naive_datetime_usec(value)
def load(:utc_datetime, value, _loader), do: load_utc_datetime(value)
def load(:utc_datetime_usec, value, _loader), do: load_utc_datetime_usec(value)
def load(mod, value, _loader), do: mod.load(value)
defp load_float(term) when is_float(term), do: {:ok, term}
defp load_float(term) when is_integer(term), do: {:ok, :erlang.float(term)}
defp load_float(_), do: :error
defp load_time(%Time{} = time), do: {:ok, truncate_usec(time)}
defp load_time(_), do: :error
defp load_time_usec(%Time{} = time), do: {:ok, pad_usec(time)}
defp load_time_usec(_), do: :error
# This is a downcast, which is always fine, and in case
# we try to send a naive datetime where a datetime is expected,
# the adapter will either explicitly error (Postgres) or it will
# accept the data (MySQL), which is fine as we always assume UTC
defp load_naive_datetime(%DateTime{} = datetime),
do: {:ok, datetime |> check_utc_timezone!(:naive_datetime) |> DateTime.to_naive() |> truncate_usec()}
defp load_naive_datetime(%NaiveDateTime{} = naive_datetime),
do: {:ok, truncate_usec(naive_datetime)}
defp load_naive_datetime(_), do: :error
defp load_naive_datetime_usec(%DateTime{} = datetime),
do: {:ok, datetime |> check_utc_timezone!(:naive_datetime_usec) |> DateTime.to_naive() |> pad_usec()}
defp load_naive_datetime_usec(%NaiveDateTime{} = naive_datetime),
do: {:ok, pad_usec(naive_datetime)}
defp load_naive_datetime_usec(_), do: :error
# This is an upcast but because we assume the database
# is always in UTC, we can perform it.
defp load_utc_datetime(%NaiveDateTime{} = naive_datetime),
do: {:ok, naive_datetime |> truncate_usec() |> DateTime.from_naive!("Etc/UTC")}
defp load_utc_datetime(%DateTime{} = datetime),
do: {:ok, datetime |> check_utc_timezone!(:utc_datetime) |> truncate_usec()}
defp load_utc_datetime(_),
do: :error
defp load_utc_datetime_usec(%NaiveDateTime{} = naive_datetime),
do: {:ok, naive_datetime |> pad_usec() |> DateTime.from_naive!("Etc/UTC")}
defp load_utc_datetime_usec(%DateTime{} = datetime),
do: {:ok, datetime |> check_utc_timezone!(:utc_datetime_usec) |> pad_usec()}
defp load_utc_datetime_usec(_),
do: :error
@doc """
Casts a value to the given type.
`cast/2` is used by the finder queries and changesets to cast outside values to
specific types.
Note that nil can be cast to all primitive types as data stores allow nil to be
set on any column.
NaN and infinite decimals are not supported, use custom types instead.
iex> cast(:any, "whatever")
{:ok, "whatever"}
iex> cast(:any, nil)
{:ok, nil}
iex> cast(:string, nil)
{:ok, nil}
iex> cast(:integer, 1)
{:ok, 1}
iex> cast(:integer, "1")
{:ok, 1}
iex> cast(:integer, "1.0")
:error
iex> cast(:id, 1)
{:ok, 1}
iex> cast(:id, "1")
{:ok, 1}
iex> cast(:id, "1.0")
:error
iex> cast(:float, 1.0)
{:ok, 1.0}
iex> cast(:float, 1)
{:ok, 1.0}
iex> cast(:float, "1")
{:ok, 1.0}
iex> cast(:float, "1.0")
{:ok, 1.0}
iex> cast(:float, "1-foo")
:error
iex> cast(:boolean, true)
{:ok, true}
iex> cast(:boolean, false)
{:ok, false}
iex> cast(:boolean, "1")
{:ok, true}
iex> cast(:boolean, "0")
{:ok, false}
iex> cast(:boolean, "whatever")
:error
iex> cast(:string, "beef")
{:ok, "beef"}
iex> cast(:binary, "beef")
{:ok, "beef"}
iex> cast(:decimal, Decimal.new("1.0"))
{:ok, Decimal.new("1.0")}
iex> cast(:decimal, "1.0bad")
:error
iex> cast({:array, :integer}, [1, 2, 3])
{:ok, [1, 2, 3]}
iex> cast({:array, :integer}, ["1", "2", "3"])
{:ok, [1, 2, 3]}
iex> cast({:array, :string}, [1, 2, 3])
:error
iex> cast(:string, [1, 2, 3])
:error
"""
@spec cast(t, term) :: {:ok, term} | {:error, keyword()} | :error
def cast({:parameterized, type, params}, value), do: type.cast(value, params)
def cast({:in, _type}, nil), do: :error
def cast(_type, nil), do: {:ok, nil}
def cast({:maybe, type}, value) do
case cast(type, value) do
{:ok, _} = ok -> ok
_ -> {:ok, value}
end
end
def cast(type, value) do
cast_fun(type).(value)
end
defp cast_fun(:integer), do: &cast_integer/1
defp cast_fun(:float), do: &cast_float/1
defp cast_fun(:boolean), do: &cast_boolean/1
defp cast_fun(:map), do: &cast_map/1
defp cast_fun(:string), do: &cast_binary/1
defp cast_fun(:binary), do: &cast_binary/1
defp cast_fun(:id), do: &cast_integer/1
defp cast_fun(:binary_id), do: &cast_binary/1
defp cast_fun(:any), do: &{:ok, &1}
defp cast_fun(:decimal), do: &cast_decimal/1
defp cast_fun(:date), do: &cast_date/1
defp cast_fun(:time), do: &maybe_truncate_usec(cast_time(&1))
defp cast_fun(:time_usec), do: &maybe_pad_usec(cast_time(&1))
defp cast_fun(:naive_datetime), do: &maybe_truncate_usec(cast_naive_datetime(&1))
defp cast_fun(:naive_datetime_usec), do: &maybe_pad_usec(cast_naive_datetime(&1))
defp cast_fun(:utc_datetime), do: &maybe_truncate_usec(cast_utc_datetime(&1))
defp cast_fun(:utc_datetime_usec), do: &maybe_pad_usec(cast_utc_datetime(&1))
defp cast_fun({:param, :any_datetime}), do: &cast_any_datetime(&1)
defp cast_fun({:parameterized, mod, params}), do: &mod.cast(&1, params)
defp cast_fun({:in, type}), do: cast_fun({:array, type})
defp cast_fun({:array, {:parameterized, _, _} = type}) do
fun = cast_fun(type)
&array(&1, fun, false, [])
end
defp cast_fun({:array, type}) do
fun = cast_fun(type)
&array(&1, fun, true, [])
end
defp cast_fun({:map, {:parameterized, _, _} = type}) do
fun = cast_fun(type)
&map(&1, fun, false, %{})
end
defp cast_fun({:map, type}) do
fun = cast_fun(type)
&map(&1, fun, true, %{})
end
defp cast_fun(mod) when is_atom(mod) do
fn
nil -> {:ok, nil}
value -> mod.cast(value)
end
end
defp cast_integer(term) when is_binary(term) do
case Integer.parse(term) do
{integer, ""} -> {:ok, integer}
_ -> :error
end
end
defp cast_integer(term) when is_integer(term), do: {:ok, term}
defp cast_integer(_), do: :error
defp cast_float(term) when is_binary(term) do
case Float.parse(term) do
{float, ""} -> {:ok, float}
_ -> :error
end
end
defp cast_float(term) when is_float(term), do: {:ok, term}
defp cast_float(term) when is_integer(term), do: {:ok, :erlang.float(term)}
defp cast_float(_), do: :error
defp cast_decimal(term) when is_binary(term) do
case Decimal.parse(term) do
{:ok, decimal} -> check_decimal(decimal, false)
# The following two clauses exist to support earlier versions of Decimal.
{decimal, ""} -> check_decimal(decimal, false)
{_, remainder} when is_binary(remainder) and byte_size(remainder) > 0 -> :error
:error -> :error
end
end
defp cast_decimal(term), do: same_decimal(term)
defp cast_boolean(term) when term in ~w(true 1), do: {:ok, true}
defp cast_boolean(term) when term in ~w(false 0), do: {:ok, false}
defp cast_boolean(term) when is_boolean(term), do: {:ok, term}
defp cast_boolean(_), do: :error
defp cast_binary(term) when is_binary(term), do: {:ok, term}
defp cast_binary(_), do: :error
defp cast_map(term) when is_map(term), do: {:ok, term}
defp cast_map(_), do: :error
## Shared helpers
@compile {:inline, same_integer: 1, same_boolean: 1, same_map: 1, same_decimal: 1, same_date: 1}
defp same_integer(term) when is_integer(term), do: {:ok, term}
defp same_integer(_), do: :error
defp same_boolean(term) when is_boolean(term), do: {:ok, term}
defp same_boolean(_), do: :error
defp same_binary(term) when is_binary(term), do: {:ok, term}
defp same_binary(_), do: :error
defp same_map(term) when is_map(term), do: {:ok, term}
defp same_map(_), do: :error
defp same_decimal(term) when is_integer(term), do: {:ok, Decimal.new(term)}
defp same_decimal(term) when is_float(term), do: {:ok, Decimal.from_float(term)}
defp same_decimal(%Decimal{} = term), do: check_decimal(term, true)
defp same_decimal(_), do: :error
defp same_date(%Date{} = term), do: {:ok, term}
defp same_date(_), do: :error
@doc false
def empty_trimmed_string?(value) do
is_binary(value) and String.trim_leading(value) == ""
end
## Adapter related
@doc false
def adapter_autogenerate(adapter, type) do
type
|> type()
|> adapter.autogenerate()
end
@doc false
def adapter_load(adapter, {:parameterized, module, params} = type, value) do
process_loaders(adapter.loaders(module.type(params), type), {:ok, value}, adapter)
end
def adapter_load(_adapter, _type, nil) do
{:ok, nil}
end
def adapter_load(adapter, type, value) do
if of_base_type?(type, value) do
{:ok, value}
else
process_loaders(adapter.loaders(type(type), type), {:ok, value}, adapter)
end
end
defp process_loaders(_, :error, _adapter),
do: :error
defp process_loaders([fun|t], {:ok, value}, adapter) when is_function(fun),
do: process_loaders(t, fun.(value), adapter)
defp process_loaders([type|t], {:ok, value}, adapter),
do: process_loaders(t, load(type, value, &adapter_load(adapter, &1, &2)), adapter)
defp process_loaders([], {:ok, _} = acc, _adapter),
do: acc
@doc false
def adapter_dump(adapter, {:parameterized, module, params} = type, value) do
process_dumpers(adapter.dumpers(module.type(params), type), {:ok, value}, adapter)
end
def adapter_dump(_adapter, type, nil) do
dump(type, nil)
end
def adapter_dump(adapter, type, value) do
process_dumpers(adapter.dumpers(type(type), type), {:ok, value}, adapter)
end
defp process_dumpers(_, :error, _adapter),
do: :error
defp process_dumpers([fun|t], {:ok, value}, adapter) when is_function(fun),
do: process_dumpers(t, fun.(value), adapter)
defp process_dumpers([type|t], {:ok, value}, adapter),
do: process_dumpers(t, dump(type, value, &adapter_dump(adapter, &1, &2)), adapter)
defp process_dumpers([], {:ok, _} = acc, _adapter),
do: acc
## Date
defp cast_date(binary) when is_binary(binary) do
case Date.from_iso8601(binary) do
{:ok, _} = ok ->
ok
{:error, _} ->
case NaiveDateTime.from_iso8601(binary) do
{:ok, naive_datetime} -> {:ok, NaiveDateTime.to_date(naive_datetime)}
{:error, _} -> :error
end
end
end
defp cast_date(%{"year" => empty, "month" => empty, "day" => empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_date(%{year: empty, month: empty, day: empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_date(%{"year" => year, "month" => month, "day" => day}),
do: cast_date(to_i(year), to_i(month), to_i(day))
defp cast_date(%{year: year, month: month, day: day}),
do: cast_date(to_i(year), to_i(month), to_i(day))
defp cast_date(_),
do: :error
defp cast_date(year, month, day) when is_integer(year) and is_integer(month) and is_integer(day) do
case Date.new(year, month, day) do
{:ok, _} = ok -> ok
{:error, _} -> :error
end
end
defp cast_date(_, _, _),
do: :error
## Time
defp cast_time(<<hour::2-bytes, ?:, minute::2-bytes>>),
do: cast_time(to_i(hour), to_i(minute), 0, nil)
defp cast_time(binary) when is_binary(binary) do
case Time.from_iso8601(binary) do
{:ok, _} = ok -> ok
{:error, _} -> :error
end
end
defp cast_time(%{"hour" => empty, "minute" => empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_time(%{hour: empty, minute: empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_time(%{"hour" => hour, "minute" => minute} = map),
do: cast_time(to_i(hour), to_i(minute), to_i(Map.get(map, "second")), to_i(Map.get(map, "microsecond")))
defp cast_time(%{hour: hour, minute: minute, second: second, microsecond: {microsecond, precision}}),
do: cast_time(to_i(hour), to_i(minute), to_i(second), {to_i(microsecond), to_i(precision)})
defp cast_time(%{hour: hour, minute: minute} = map),
do: cast_time(to_i(hour), to_i(minute), to_i(Map.get(map, :second)), to_i(Map.get(map, :microsecond)))
defp cast_time(_),
do: :error
defp cast_time(hour, minute, sec, usec) when is_integer(usec) do
cast_time(hour, minute, sec, {usec, 6})
end
defp cast_time(hour, minute, sec, nil) do
cast_time(hour, minute, sec, {0, 0})
end
defp cast_time(hour, minute, sec, {usec, precision})
when is_integer(hour) and is_integer(minute) and
(is_integer(sec) or is_nil(sec)) and is_integer(usec) and is_integer(precision) do
case Time.new(hour, minute, sec || 0, {usec, precision}) do
{:ok, _} = ok -> ok
{:error, _} -> :error
end
end
defp cast_time(_, _, _, _) do
:error
end
defp cast_any_datetime(%DateTime{} = datetime), do: cast_utc_datetime(datetime)
defp cast_any_datetime(other), do: cast_naive_datetime(other)
## Naive datetime
defp cast_naive_datetime("-" <> rest) do
with {:ok, naive_datetime} <- cast_naive_datetime(rest) do
{:ok, %{naive_datetime | year: naive_datetime.year * -1}}
end
end
defp cast_naive_datetime(<<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes, sep, hour::2-bytes, ?:, minute::2-bytes>>)
when sep in [?\s, ?T] do
case NaiveDateTime.new(to_i(year), to_i(month), to_i(day), to_i(hour), to_i(minute), 0) do
{:ok, _} = ok -> ok
_ -> :error
end
end
defp cast_naive_datetime(binary) when is_binary(binary) do
case NaiveDateTime.from_iso8601(binary) do
{:ok, _} = ok -> ok
{:error, _} -> :error
end
end
defp cast_naive_datetime(%{"year" => empty, "month" => empty, "day" => empty,
"hour" => empty, "minute" => empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_naive_datetime(%{year: empty, month: empty, day: empty,
hour: empty, minute: empty}) when empty in ["", nil],
do: {:ok, nil}
defp cast_naive_datetime(%{} = map) do
with {:ok, %Date{} = date} <- cast_date(map),
{:ok, %Time{} = time} <- cast_time(map) do
NaiveDateTime.new(date, time)
else
_ -> :error
end
end
defp cast_naive_datetime(_) do
:error
end
## UTC datetime
defp cast_utc_datetime("-" <> rest) do
with {:ok, utc_datetime} <- cast_utc_datetime(rest) do
{:ok, %{utc_datetime | year: utc_datetime.year * -1}}
end
end
defp cast_utc_datetime(<<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes, sep, hour::2-bytes, ?:, minute::2-bytes>>)
when sep in [?\s, ?T] do
case NaiveDateTime.new(to_i(year), to_i(month), to_i(day), to_i(hour), to_i(minute), 0) do
{:ok, naive_datetime} -> {:ok, DateTime.from_naive!(naive_datetime, "Etc/UTC")}
_ -> :error
end
end
defp cast_utc_datetime(binary) when is_binary(binary) do
case DateTime.from_iso8601(binary) do
{:ok, datetime, _offset} -> {:ok, datetime}
{:error, :missing_offset} ->
case NaiveDateTime.from_iso8601(binary) do
{:ok, naive_datetime} -> {:ok, DateTime.from_naive!(naive_datetime, "Etc/UTC")}
{:error, _} -> :error
end
{:error, _} -> :error
end
end
defp cast_utc_datetime(%DateTime{time_zone: "Etc/UTC"} = datetime), do: {:ok, datetime}
defp cast_utc_datetime(%DateTime{} = datetime) do
case (datetime |> DateTime.to_unix(:microsecond) |> DateTime.from_unix(:microsecond)) do
{:ok, _} = ok -> ok
{:error, _} -> :error
end
end
defp cast_utc_datetime(value) do
case cast_naive_datetime(value) do
{:ok, %NaiveDateTime{} = naive_datetime} ->
{:ok, DateTime.from_naive!(naive_datetime, "Etc/UTC")}
{:ok, _} = ok ->
ok
:error ->
:error
end
end
@doc """
Checks if two terms are equal.
Depending on the given `type` performs a structural or semantical comparison.
## Examples
iex> equal?(:integer, 1, 1)
true
iex> equal?(:decimal, Decimal.new("1"), Decimal.new("1.00"))
true
"""
@spec equal?(t, term, term) :: boolean
def equal?(_, nil, nil), do: true
def equal?(type, term1, term2) do
if fun = equal_fun(type) do
fun.(term1, term2)
else
term1 == term2
end
end
@doc """
Checks if `collection` includes a `term`.
Depending on the given `type` performs a structural or semantical comparison.
## Examples
iex> include?(:integer, 1, 1..3)
true
iex> include?(:decimal, Decimal.new("1"), [Decimal.new("1.00"), Decimal.new("2.00")])
true
"""
@spec include?(t, term, Enum.t()) :: boolean
def include?(type, term, collection) do
if fun = equal_fun(type) do
Enum.any?(collection, &fun.(term, &1))
else
term in collection
end
end
defp equal_fun(:decimal), do: &equal_decimal?/2
defp equal_fun(t) when t in [:time, :time_usec], do: &equal_time?/2
defp equal_fun(t) when t in [:utc_datetime, :utc_datetime_usec], do: &equal_utc_datetime?/2
defp equal_fun(t) when t in [:naive_datetime, :naive_datetime_usec], do: &equal_naive_datetime?/2
defp equal_fun(t) when t in @base, do: nil
defp equal_fun({:array, type}) do
if fun = equal_fun(type) do
&equal_list?(fun, &1, &2)
end
end
defp equal_fun({:map, type}) do
if fun = equal_fun(type) do
&equal_map?(fun, &1, &2)
end
end
defp equal_fun({:parameterized, mod, params}) do
&mod.equal?(&1, &2, params)
end
defp equal_fun(mod) when is_atom(mod), do: &mod.equal?/2
defp equal_decimal?(%Decimal{} = a, %Decimal{} = b), do: Decimal.equal?(a, b)
defp equal_decimal?(_, _), do: false
defp equal_time?(%Time{} = a, %Time{} = b), do: Time.compare(a, b) == :eq
defp equal_time?(_, _), do: false
defp equal_utc_datetime?(%DateTime{} = a, %DateTime{} = b), do: DateTime.compare(a, b) == :eq
defp equal_utc_datetime?(_, _), do: false
defp equal_naive_datetime?(%NaiveDateTime{} = a, %NaiveDateTime{} = b),
do: NaiveDateTime.compare(a, b) == :eq
defp equal_naive_datetime?(_, _),
do: false
defp equal_list?(fun, [nil | xs], [nil | ys]), do: equal_list?(fun, xs, ys)
defp equal_list?(fun, [x | xs], [y | ys]), do: fun.(x, y) and equal_list?(fun, xs, ys)
defp equal_list?(_fun, [], []), do: true
defp equal_list?(_fun, _, _), do: false
defp equal_map?(_fun, map1, map2) when map_size(map1) != map_size(map2) do
false
end
defp equal_map?(fun, %{} = map1, %{} = map2) do
equal_map?(fun, Map.to_list(map1), map2)
end
defp equal_map?(fun, [{key, nil} | tail], other_map) do
case other_map do
%{^key => nil} -> equal_map?(fun, tail, other_map)
_ -> false
end
end
defp equal_map?(fun, [{key, val} | tail], other_map) do
case other_map do
%{^key => other_val} -> fun.(val, other_val) and equal_map?(fun, tail, other_map)
_ -> false
end
end
defp equal_map?(_fun, [], _) do
true
end
defp equal_map?(_fun, _, _) do
false
end
@doc """
Format type for error messaging and logs.
"""
def format({composite, type}) when composite in [:array, :map] do
"{#{inspect(composite)}, #{format(type)}}"
end
def format({:parameterized, type, params}) do
if function_exported?(type, :format, 1) do
apply(type, :format, [params])
else
"##{inspect(type)}<#{inspect(params)}>"
end
end
def format(type), do: inspect(type)
## Helpers
# Checks if a value is of the given primitive type.
defp of_base_type?(:any, _), do: true
defp of_base_type?(:id, term), do: is_integer(term)
defp of_base_type?(:float, term), do: is_float(term)
defp of_base_type?(:integer, term), do: is_integer(term)
defp of_base_type?(:boolean, term), do: is_boolean(term)
defp of_base_type?(:binary, term), do: is_binary(term)
defp of_base_type?(:string, term), do: is_binary(term)
defp of_base_type?(:map, term), do: is_map(term) and not Map.has_key?(term, :__struct__)
defp of_base_type?(:decimal, value), do: Kernel.match?(%Decimal{}, value)
defp of_base_type?(:date, value), do: Kernel.match?(%Date{}, value)
defp of_base_type?(_, _), do: false
defp array([nil | t], fun, true, acc) do
array(t, fun, true, [nil | acc])
end
defp array([h | t], fun, skip_nil?, acc) do
case fun.(h) do
{:ok, h} -> array(t, fun, skip_nil?, [h | acc])
:error -> :error
{:error, _custom_errors} -> :error
end
end
defp array([], _fun, _skip_nil?,acc) do
{:ok, Enum.reverse(acc)}
end
defp array(_, _, _, _) do
:error
end
defp map(map, fun, skip_nil?, acc) when is_map(map) do
map_each(Map.to_list(map), fun, skip_nil?, acc)
end
defp map(_, _, _, _) do
:error
end
defp map_each([{key, nil} | t], fun, true, acc) do
map_each(t, fun, true, Map.put(acc, key, nil))
end
defp map_each([{key, value} | t], fun, skip_nil?, acc) do
case fun.(value) do
{:ok, value} -> map_each(t, fun, skip_nil?, Map.put(acc, key, value))
:error -> :error
{:error, _custom_errors} -> :error
end
end
defp map_each([], _fun, _skip_nil?, acc) do
{:ok, acc}
end
defp array([nil | t], type, fun, true, acc) do
array(t, type, fun, true, [nil | acc])
end
defp array([h | t], type, fun, skip_nil?, acc) do
case fun.(type, h) do
{:ok, h} -> array(t, type, fun, skip_nil?, [h | acc])
:error -> :error
end
end
defp array([], _type, _fun, _skip_nil?, acc) do
{:ok, Enum.reverse(acc)}
end
defp array(_, _, _, _, _) do
:error
end
defp map(map, type, fun, skip_nil?, acc) when is_map(map) do
map_each(Map.to_list(map), type, fun, skip_nil?, acc)
end
defp map(_, _, _, _, _) do
:error
end
defp map_each([{key, value} | t], type, fun, skip_nil?, acc) do
case fun.(type, value) do
{:ok, value} -> map_each(t, type, fun, skip_nil?, Map.put(acc, key, value))
:error -> :error
end
end
defp map_each([], _type, _fun, _skip_nil?, acc) do
{:ok, acc}
end
defp to_i(nil), do: nil
defp to_i(int) when is_integer(int), do: int
defp to_i(bin) when is_binary(bin) do
case Integer.parse(bin) do
{int, ""} -> int
_ -> nil
end
end
defp maybe_truncate_usec({:ok, struct}), do: {:ok, truncate_usec(struct)}
defp maybe_truncate_usec(:error), do: :error
defp maybe_pad_usec({:ok, struct}), do: {:ok, pad_usec(struct)}
defp maybe_pad_usec(:error), do: :error
defp truncate_usec(nil), do: nil
defp truncate_usec(%{microsecond: {0, 0}} = struct), do: struct
defp truncate_usec(struct), do: %{struct | microsecond: {0, 0}}
defp pad_usec(nil), do: nil
defp pad_usec(%{microsecond: {_, 6}} = struct), do: struct
defp pad_usec(%{microsecond: {microsecond, _}} = struct),
do: %{struct | microsecond: {microsecond, 6}}
defp check_utc_timezone!(%{time_zone: "Etc/UTC"} = datetime, _kind), do: datetime
defp check_utc_timezone!(datetime, kind) do
raise ArgumentError,
"#{inspect kind} expects the time zone to be \"Etc/UTC\", got `#{inspect(datetime)}`"
end
defp check_usec!(%{microsecond: {_, 6}} = datetime, _kind), do: datetime
defp check_usec!(datetime, kind) do
raise ArgumentError,
"#{inspect(kind)} expects microsecond precision, got: #{inspect(datetime)}"
end
defp check_no_usec!(%{microsecond: {0, 0}} = datetime, _kind), do: datetime
defp check_no_usec!(%struct{} = datetime, kind) do
raise ArgumentError, """
#{inspect(kind)} expects microseconds to be empty, got: #{inspect(datetime)}
Use `#{inspect(struct)}.truncate(#{kind}, :second)` (available in Elixir v1.6+) to remove microseconds.
"""
end
defp check_decimal(%Decimal{coef: coef} = decimal, _) when is_integer(coef), do: {:ok, decimal}
defp check_decimal(_decimal, false), do: :error
defp check_decimal(decimal, true) do
raise ArgumentError, """
#{inspect(decimal)} is not allowed for type :decimal
`+Infinity`, `-Infinity`, and `NaN` values are not supported, even though the `Decimal` library handles them. \
To support them, you can create a custom type.
"""
end
end
