want v1.1.1 Want

Type conversion library for Elixir and Erlang.

Link to this section Summary

Functions

Cast a value to an atom.

Dump a casted input into a more serializable form. Typically used to generate Phoenix query parameters.

Cast an input value to an enum. The input must loosely match one of the allowed values in order for the cast to succeed.

Convert a value to a float.

Convert a value to an integer.

Cast an incoming keyword list or map to an output map using the provided schema to control conversion rules and validations. Each value in the schema map represents conversion options.

Cast an input to a sort tuple.

Convert a value to a string.

Link to this section Functions

Cast a value to an atom.

Options

  • :exists - If true, only convert to an atom if a matching atom already exists.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.atom("hello")

iex> Want.atom(1.0)

iex> Want.atom({:a, :b}) {:error, "Failed to convert value {:a, :b} to atom."}

iex> Want.atom({:a, :b}, default: :c)

iex> Want.atom("10", exists: true)

Link to this function

atom(value, default)

Link to this function

atom!(value, default)

Dump a casted input into a more serializable form. Typically used to generate Phoenix query parameters.

Options

  • :update - Update the input value using Want.Update protocol before dumping

Examples

iex> Want.dump({:inserted_at, :desc})

iex> Want.dump({:inserted_at, :desc}, update: :inserted_at)

iex> Want.dump({:inserted_at, :desc}, update: :updated_at)

iex> Want.dump("hello")

iex> Want.dump(%{hello: :world, sort: {:inserted_at, :desc}})

iex> Want.dump(%{hello: :world, sort: {:inserted_at, :desc}}, update: [sort: :inserted_at])

iex> Want.dump({:a, :b, :c}) {:error, "Unrecognized dump input {:a, :b, :c}"}

Link to this function

dump(input, opts)

Link to this function

dump!(input, opts)

Link to this function

enum(input, opts)

Cast an input value to an enum. The input must loosely match one of the allowed values in order for the cast to succeed.

Options

  • :valid - List of valid enum values. The input must loosely match one of these.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.enum("hello", valid: [:hello, :world])

iex> Want.enum("hello", valid: ["hello", :world])

iex> Want.enum("foo", valid: ["hello", :world], default: :bar)

Link to this function

enum!(input, opts)

Convert a value to a float.

Options

  • :max - Maximum allowable float value.
  • :min - Minimum allowable float value.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.float(1.0)

iex> Want.float({:a, :b}, default: 1.0)

iex> Want.float(:'5.0', max: 3.0)

iex> Want.float("1.0", min: 3.0)

Link to this function

float(value, default)

Link to this function

float!(value, default)

Convert a value to an integer.

Options

  • :max - Maximum allowable integer value.
  • :min - Minimum allowable integer value.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.integer(1.0)

iex> Want.integer({:a, :b}, default: 1)

iex> Want.integer(:'5', max: 3)

iex> Want.integer("1", min: 3)

Link to this function

integer(value, default)

Link to this function

integer!(value)

Link to this function

integer!(value, default)

Link to this function

map(input, schema)

Cast an incoming keyword list or map to an output map using the provided schema to control conversion rules and validations. Each value in the schema map represents conversion options.

Specify a :type field to cast the input value for a given key to that type, defaults to :string. Specific conversion and validation options for each type corresponds to those available for Want.integer/2, Want.float/2, Want.string/2 and Want.atom/2.

Maps can be nested by using

Examples

iex> Want.map(%{"id" => 1}, %{id: [type: :integer]}) {:ok, %{id: 1}}

iex> Want.map(%{}, %{id: [type: :integer, default: 1]}) {:ok, %{id: 1}}

iex> Want.map(%{"id" => "bananas"}, %{id: [type: :integer, default: 1]}) {:ok, %{id: 1}}

iex> Want.map(%{"hello" => "world", "foo" => "bar"}, %{hello: [], foo: [type: :atom]}) {:ok, %{hello: "world", foo: :bar}}

iex> Want.map(%{"hello" => %{"foo" => "bar"}}, %{hello: %{foo: [type: :atom]}}) {:ok, %{hello: %{foo: :bar}}}

Link to this function

map!(input, schema)

Link to this function

sort(input, opts)

Cast an input to a sort tuple.

Options

  • :fields - List of allowed sort fields. Casting will fail if the input doesn't match any of these.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.sort("inserted_at:desc", fields: [:inserted_at, :id, :name]) {:ok, {:inserted_at, :desc}}

iex> Want.sort("updated_at", fields: [:inserted_at, :id], default: {:id, :asc}) {:ok, {:id, :asc}}

iex> Want.sort("updated_at:asc", [])

Link to this function

sort!(input, opts)

Convert a value to a string.

Options

  • :max - Maximum allowable string length.
  • :min - Minimum allowable string length.
  • ':decode' - Currently only supports :uri; runs URI.decode on the input value
  • :matches - The resulting string must match the given regex.
  • :default - If conversion fails, this value should be returned instead.

Examples

iex> Want.string(1)

iex> Want.string({:a, :b}, default: "string")

iex> Want.string(:hello, max: 3)

iex> Want.string("hello%20world", decode: :uri)

iex> Want.string(:a, min: 3)

iex> Want.string(:a, matches: ~r/a/)

Link to this function

string(value, default)

Link to this function

string!(value, default)