= cowboy_req:match_qs(3)

== Name

cowboy_req:match_qs - Match the query string against constraints

== Description

[source,erlang]
----
match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req())
    -> #{atom() => any()}
----

Parse the query string and match specific values against
constraints.

This function allows easily retrieving expected values
from the query string, validating and converting them
in one call. In addition, the keys are converted to
atoms, making manipulation that much simpler.

== Arguments

Fields::

Fields to retrieve from the query string.
+
See link:man:cowboy(3)[cowboy(3)] for a complete description.

Req::

The Req object.

== Return value

Desired values are returned as a map. The key is the atom
that was given in the list of fields, and the value is the
optionally converted value after applying constraints.

The map contains the same keys that were given in the fields.

An exception is triggered when the match fails.

== Changelog

* *2.0*: Function introduced.

== Examples

.Match fields
[source,erlang]
----
%% ID and Lang are binaries.
#{id := ID, lang := Lang}
    = cowboy_req:match_qs([id, lang], Req).
----

.Match fields and apply constraints
[source,erlang]
----
%% ID is an integer and Lang a non-empty binary.
#{id := ID, lang := Lang}
    = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).
----

.Match fields with default values
[source,erlang]
----
#{lang := Lang}
    = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
----

== See also

link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:qs(3)[cowboy_req:qs(3)],
link:man:cowboy_req:parse_qs(3)[cowboy_req:parse_qs(3)]