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
atom(value)
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)
atom(value, default)
atom!(value)
atom!(value, default)
dump(input)
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}"}
dump(input, opts)
dump!(input)
dump!(input, opts)
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)
enum!(input, opts)
float(value)
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)
float(value, default)
float!(value)
float!(value, default)
integer(value)
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)
integer(value, default)
integer!(value)
integer!(value, default)
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}}}
map!(input, schema)
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", [])
sort!(input, opts)
string(value)
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/)