View Source Flop.Filter (Flop v0.19.0)

@type op() ::
  :==
  | :!=
  | :=~
  | :empty
  | :not_empty
  | :<=
  | :<
  | :>=
  | :>
  | :in
  | :not_in
  | :contains
  | :not_contains
  | :like
  | :not_like
  | :like_and
  | :like_or
  | :ilike
  | :not_ilike
  | :ilike_and
  | :ilike_or

Represents valid filter operators.

Operator	Value	WHERE clause
`:==`	`"Salicaceae"`	`WHERE column = 'Salicaceae'`
`:!=`	`"Salicaceae"`	`WHERE column != 'Salicaceae'`
`:=~`	`"cyth"`	`WHERE column ILIKE '%cyth%'`
`:empty`	`true`	`WHERE (column IS NULL) = true`
`:empty`	`false`	`WHERE (column IS NULL) = false`
`:not_empty`	`true`	`WHERE (column IS NOT NULL) = true`
`:not_empty`	`false`	`WHERE (column IS NOT NULL) = false`
`:<=`	`10`	`WHERE column <= 10`
`:<`	`10`	`WHERE column < 10`
`:>=`	`10`	`WHERE column >= 10`
`:>`	`10`	`WHERE column > 10`
`:in`	`["pear", "plum"]`	`WHERE column = ANY('pear', 'plum')`
`:not_in`	`["pear", "plum"]`	`WHERE column = NOT IN('pear', 'plum')`
`:contains`	`"pear"`	`WHERE 'pear' = ANY(column)`
`:not_contains`	`"pear"`	`WHERE 'pear' = NOT IN(column)`
`:like`	`"cyth"`	`WHERE column LIKE '%cyth%'`
`:not_like`	`"cyth"`	`WHERE column NOT LIKE '%cyth%'`
`:like_and`	`["Rubi", "Rosa"]`	`WHERE column LIKE '%Rubi%' AND column LIKE '%Rosa%'`
`:like_and`	`"Rubi Rosa"`	`WHERE column LIKE '%Rubi%' AND column LIKE '%Rosa%'`
`:like_or`	`["Rubi", "Rosa"]`	`WHERE column LIKE '%Rubi%' OR column LIKE '%Rosa%'`
`:like_or`	`"Rubi Rosa"`	`WHERE column LIKE '%Rubi%' OR column LIKE '%Rosa%'`
`:ilike`	`"cyth"`	`WHERE column ILIKE '%cyth%'`
`:not_ilike`	`"cyth"`	`WHERE column NOT ILIKE '%cyth%'`
`:ilike_and`	`["Rubi", "Rosa"]`	`WHERE column ILIKE '%Rubi%' AND column ILIKE '%Rosa%'`
`:ilike_and`	`"Rubi Rosa"`	`WHERE column ILIKE '%Rubi%' AND column ILIKE '%Rosa%'`
`:ilike_or`	`["Rubi", "Rosa"]`	`WHERE column ILIKE '%Rubi%' OR column ILIKE '%Rosa%'`
`:ilike_or`	`"Rubi Rosa"`	`WHERE column ILIKE '%Rubi%' OR column ILIKE '%Rosa%'`

The filter operators :ilike_and, :ilike_or, :like_and and :like_or accept both strings and list of strings.

If the filter value is a string, it will be split at whitespace characters and the segments are combined with and or or.
If a list of strings is passed, the individual strings are not split, and the list items are combined with and or or.

t()

@type t() :: %Flop.Filter{field: atom() | String.t(), op: op(), value: any()}

Represents filter query parameters.

fields
Fields

field: The field the filter is applied to. The allowed fields can be restricted by deriving Flop.Schema in your Ecto schema.
op: The filter operator.
value: The comparison value of the filter.

Link to this section Functions

allowed_operators(type)

@spec allowed_operators(atom()) :: [op()]

Returns the allowed operators for the given Ecto type.

If the given value is not a native Ecto type, a list with all operators is returned.

iex> allowed_operators(:integer)
[:==, :!=, :empty, :not_empty, :<=, :<, :>=, :>, :in, :not_in]

allowed_operators(module, field)

@spec allowed_operators(atom(), atom()) :: [op()]

Returns the allowed operators for the given schema module and field.

For regular Ecto schema fields, the type is derived via schema reflection.

If the given schema module derives Flop.Schema, the type of join and custom fields is determined via the ecto_type option. Compound files are always handled as string fields, minus unsupported operators.

If the type cannot be determined or if the type is not a native Ecto type, a list with all operators is returned.

iex> allowed_operators(Pet, :age)
[:==, :!=, :empty, :not_empty, :<=, :<, :>=, :>, :in, :not_in]

delete(filters, field)

(since 0.19.0)

@spec delete([t()], atom()) :: [t()]

Deletes the filters for the given field from a list of filters.

examples
Examples

iex> delete(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8}
...>   ],
...>   :name
...> )
[%Flop.Filter{field: :age, op: :>, value: 8}]

iex> delete(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   :name
...> )
[%Flop.Filter{field: :age, op: :>, value: 8}]

iex> delete([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
[%Flop.Filter{field: :name, op: :==, value: "Joe"}]

delete_first(filters, field)

(since 0.19.0)

@spec delete_first([t()], atom()) :: [t()]

Deletes the first filter in list of filters for the given field.

examples
Examples

iex> delete_first(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   :name
...> )
[
  %Flop.Filter{field: :age, op: :>, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "Jim"}
]

iex> delete_first([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
[%Flop.Filter{field: :name, op: :==, value: "Joe"}]

drop(filters, fields)

(since 0.19.0)

@spec drop([t()], [atom()]) :: [t()]

Removes the filters for the given fields from a list of filters.

examples
Examples

iex> drop(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :color, op: :==, value: "blue"}
...>   ],
...>   [:name, :color]
...> )
[%Flop.Filter{field: :age, op: :>, value: 8}]

iex> drop(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :color, op: :==, value: "blue"},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   [:name, :species]
...> )
[
  %Flop.Filter{field: :age, op: :>, value: 8},
  %Flop.Filter{field: :color, op: :==, value: "blue"}
]

fetch(filters, field)

(since 0.19.0)

@spec fetch([t()], atom()) :: {:ok, t()} | :error

Fetches the first filter for the given field and returns it in a tuple.

examples
Examples

iex> fetch([], :name)
:error

iex> fetch([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :name)
{:ok, %Flop.Filter{field: :name, op: :==, value: "Joe"}}

iex> fetch([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
:error

iex> fetch(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   :name
...> )
{:ok, %Flop.Filter{field: :name, op: :==, value: "Joe"}}

get(filters, field)

(since 0.19.0)

@spec get([t()], atom()) :: t() | nil

Returns the first filter for the given field.

examples
Examples

iex> get([], :name)
nil

iex> get([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :name)
%Flop.Filter{field: :name, op: :==, value: "Joe"}

iex> get([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
nil

iex> get(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   :name
...> )
%Flop.Filter{field: :name, op: :==, value: "Joe"}

get_all(filters, field)

(since 0.19.0)

@spec get_all([t()], atom()) :: [t()]

Returns the all filters for the given field.

examples
Examples

iex> get_all([], :name)
[]

iex> get_all([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :name)
[%Flop.Filter{field: :name, op: :==, value: "Joe"}]

iex> get_all([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
[]

iex> get_all(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   :name
...> )
[
  %Flop.Filter{field: :name, op: :==, value: "Joe"},
  %Flop.Filter{field: :name, op: :==, value: "Jim"}
]

new(enum, opts \\ [])

(since 0.19.0)

@spec new(
  Enumerable.t(),
  keyword()
) :: [t()]

Creates a list of filters from an enumerable.

The default operator is :==.

iex> new(%{name: "George", age: 8})
[
  %Flop.Filter{field: :age, op: :==, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

iex> new([name: "George", age: 8])
[
  %Flop.Filter{field: :name, op: :==, value: "George"},
  %Flop.Filter{field: :age, op: :==, value: 8},
]

You can optionally pass a mapping from field names to operators as a map with atom keys.

iex> new(
...>   %{name: "George", age: 8},
...>   operators: %{name: :ilike_and}
...> )
[
  %Flop.Filter{field: :age, op: :==, value: 8},
  %Flop.Filter{field: :name, op: :ilike_and, value: "George"}
]

You can also pass a map to rename fields.

iex> new(
...>   %{s: "George", age: 8},
...>   rename: %{s: :name}
...> )
[
  %Flop.Filter{field: :age, op: :==, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

iex> new(
...>   %{s: "George", cat: true},
...>   rename: %{s: :name, cat: :dog}
...> )
[
  %Flop.Filter{field: :dog, op: :==, value: true},
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

If both a rename option and an operator are set for a field, the operator option needs to use the new field name.

iex> new(
...>   %{n: "George"},
...>   rename: %{n: :name},
...>   operators: %{name: :ilike_or}
...> )
[%Flop.Filter{field: :name, op: :ilike_or, value: "George"}]

If the enumerable uses string keys as field names, the function attempts to convert them to existing atoms. If the atom does not exist, the filter is removed from the list.

iex> new(%{"name" => "George", "age" => 8})
[
  %Flop.Filter{field: :age, op: :==, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

iex> new(%{"name" => "George", "doesnotexist" => 8})
[
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

Other key types are also removed.

iex> new(%{"name" => "George", 2 => 8})
[
  %Flop.Filter{field: :name, op: :==, value: "George"}
]

pop(filters, field, default \\ nil)

(since 0.19.0)

@spec pop([t()], atom(), any()) :: {t(), [t()]}

Returns the first filter for the given field and removes all other filters for the same field from the filter list.

Returns a tuple with the first matching filter first value for key and the remaining filter list. If there is no filter for the field in the list, the default value is returned as the first tuple element.

examples
Examples

iex> pop([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :name)
{%Flop.Filter{field: :name, op: :==, value: "Joe"}, []}

iex> pop([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
{nil, [%Flop.Filter{field: :name, op: :==, value: "Joe"}]}

iex> pop(
...>   [%Flop.Filter{field: :name, op: :==, value: "Joe"}],
...>   :age,
...>   %Flop.Filter{field: :age, op: :>, value: 8}
...> )
{
  %Flop.Filter{field: :age, op: :>, value: 8},
  [%Flop.Filter{field: :name, op: :==, value: "Joe"}]
}

iex> pop(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"},
...>   ],
...>   :name
...> )
{
  %Flop.Filter{field: :name, op: :==, value: "Joe"},
  [%Flop.Filter{field: :age, op: :>, value: 8}]
}

pop_first(filters, field, default \\ nil)

(since 0.19.0)

@spec pop_first([t()], atom(), any()) :: {t(), [t()]}

Returns the first filter for the given field and a filter list with all remaining filters.

examples
Examples

iex> pop_first([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :name)
{%Flop.Filter{field: :name, op: :==, value: "Joe"}, []}

iex> pop_first([%Flop.Filter{field: :name, op: :==, value: "Joe"}], :age)
{nil, [%Flop.Filter{field: :name, op: :==, value: "Joe"}]}

iex> pop_first(
...>   [%Flop.Filter{field: :name, op: :==, value: "Joe"}],
...>   :age,
...>   %Flop.Filter{field: :age, op: :>, value: 8}
...> )
{
  %Flop.Filter{field: :age, op: :>, value: 8},
  [%Flop.Filter{field: :name, op: :==, value: "Joe"}]
}

iex> pop_first(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"},
...>   ],
...>   :name
...> )
{
  %Flop.Filter{field: :name, op: :==, value: "Joe"},
  [
    %Flop.Filter{field: :age, op: :>, value: 8},
    %Flop.Filter{field: :name, op: :==, value: "Jim"}
  ]
}

put(filters, filter)

(since 0.19.0)

@spec put([t()], t()) :: [t()]

Adds the given filter to the filter list and removes all existing filters for the same field from the list.

examples
Examples

iex> put(
...>   [%Flop.Filter{field: :name, op: :==, value: "Joe"}],
...>   %Flop.Filter{field: :age, op: :>, value: 8}
...> )
[
  %Flop.Filter{field: :age, op: :>, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "Joe"}
]

iex> put(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   %Flop.Filter{field: :name, op: :==, value: "Jane"}
...> )
[
  %Flop.Filter{field: :name, op: :==, value: "Jane"},
  %Flop.Filter{field: :age, op: :>, value: 8}
]

put_new(filters, filter)

(since 0.19.0)

@spec put_new([t()], t()) :: [t()]

Adds the given filter to the filter list only if no filter for the field exists yet.

examples
Examples

iex> put_new(
...>   [%Flop.Filter{field: :name, op: :==, value: "Joe"}],
...>   %Flop.Filter{field: :age, op: :>, value: 8}
...> )
[
  %Flop.Filter{field: :age, op: :>, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "Joe"}
]

iex> put_new(
...>   [
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   %Flop.Filter{field: :name, op: :==, value: "Jane"}
...> )
[
  %Flop.Filter{field: :age, op: :>, value: 8},
  %Flop.Filter{field: :name, op: :==, value: "Jim"}
]

take(filters, fields)

(since 0.19.0)

@spec take([t()], [atom()]) :: [t()]

Takes all filters for the given fields from a filter list.

examples
Examples

iex> take(
...>   [
...>     %Flop.Filter{field: :name, op: :==, value: "Joe"},
...>     %Flop.Filter{field: :age, op: :>, value: 8},
...>     %Flop.Filter{field: :color, op: :==, value: "blue"},
...>     %Flop.Filter{field: :name, op: :==, value: "Jim"}
...>   ],
...>   [:name, :color]
...> )
[
  %Flop.Filter{field: :name, op: :==, value: "Joe"},
  %Flop.Filter{field: :color, op: :==, value: "blue"},
  %Flop.Filter{field: :name, op: :==, value: "Jim"}
]

Settings View Source Flop.Filter (Flop v0.19.0)

Link to this section Summary

Types

Functions

Link to this section Types

op()

t()

fields Fields

Link to this section Functions

allowed_operators(type)

allowed_operators(module, field)

delete(filters, field)

examples Examples

delete_first(filters, field)

examples Examples

drop(filters, fields)

examples Examples

fetch(filters, field)

examples Examples

get(filters, field)

examples Examples

get_all(filters, field)

examples Examples

new(enum, opts \\ [])

pop(filters, field, default \\ nil)

examples Examples

pop_first(filters, field, default \\ nil)

examples Examples

put(filters, filter)

examples Examples

put_new(filters, filter)

examples Examples

take(filters, fields)

examples Examples

View Source Flop.Filter (Flop v0.19.0)

fields
Fields

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples

examples
Examples