What is the difference between Ecto.Type's cast and dump?

vivus-ignis · April 30, 2017, 2:05pm

Hello there!

Trying to sketch a custom type to store a string as a tsvector in a database. Right now I’m stuck trying to understand the difference between cast and dump functions. Documentation is not terribly helpful here:

cast(type, value)
Casts a value to the given type

dump(type, value, dumper \ &dump/2)
Dumps a value to the given type

Would appreciate any help. Thanks in advance.

kokolegorille · April 30, 2017, 2:12pm

cast and load transform data.
dump is a guard guard clause.

eg: atom_to_string and reverse…

defmodule Whatever.Atom do
  @behaviour Ecto.Type
  def type, do: :binary
  
  def cast(atom) when is_atom(atom), do: {:ok, to_string(atom)}
  def cast(string) when is_binary(string), do: {:ok, string}
  def cast(_), do: :error
  
  def load(string) when is_binary(string), do: {:ok, String.to_atom(string)}
  def load(_), do: :error
  
  def dump(string) when is_binary(string), do: {:ok, string}
  def dump(_), do: :error
end

wmnnd · April 30, 2017, 2:54pm

cast/2 is the function used when you call Ecto.Changeset.cast/3 while dump/2 is used to get your data ready to be written to the database.

This means that cast is used to (potentially) convert your data into an internal normalized representation which will be part of your changesets. It also used for verifying that something is actually valid input data for your type.

The Ecto.Date module has some nice examples of it in its source code. As you can see there, cast/2 is used to normalize input from several different formats …

github.com

elixir-ecto/ecto/blob/v2.1.4/lib/ecto/date_time.ex#L141


@doc """
Same as `cast/1` but raises `Ecto.CastError` on invalid dates.
"""
def cast!(value) do
  case cast(value) do
    {:ok, date} -> date
    :error -> raise Ecto.CastError, "cannot cast #{inspect value} to date"
  end
end


defp do_cast(<<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes>>),
  do: from_parts(to_i(year), to_i(month), to_i(day))
defp do_cast(<<year::4-bytes, ?-, month::2-bytes, ?-, day::2-bytes, sep,
           _hour::2-bytes, ?:, _min::2-bytes, ?:, _sec::2-bytes, _rest::binary>>) when sep in [?\s, ?T],
  do: from_parts(to_i(year), to_i(month), to_i(day))
defp do_cast(%Ecto.Date{} = d),
  do: {:ok, d}
defp do_cast(%{"year" => empty, "month" => empty, "day" => empty}) when empty in ["", nil],
  do: {:ok, nil}
defp do_cast(%{year: empty, month: empty, day: empty}) when empty in ["", nil],
  do: {:ok, nil}

… while dump/2 simply prepares the data to be written to the database:

github.com

elixir-ecto/ecto/blob/v2.1.4/lib/ecto/date_time.ex#L175


end


defp from_parts(year, month, day) when is_date(year, month, day) do
  {:ok, %Ecto.Date{year: year, month: month, day: day}}
end
defp from_parts(_, _, _), do: :error


@doc """
Converts an `Ecto.Date` into a date triplet.
"""
def dump(%Ecto.Date{year: year, month: month, day: day}) do
  {:ok, {year, month, day}}
end
def dump(_), do: :error


@doc """
Converts a date triplet into an `Ecto.Date`.
"""
def load({year, month, day}) do
  {:ok, %Ecto.Date{year: year, month: month, day: day}}
end