```{index} single: URL::Encode::XS ``` # URL::Encode::XS ```{pperl-module-badges} URL::Encode::XS ``` Encode and decode the `application/x-www-form-urlencoded` form of strings, and split a query string into its parameters. This is the fast half of URL::Encode: `URL::Encode` loads it when it is there, and falls back to its pure-Perl `URL::Encode::PP`, which gives the same results, otherwise (or when `URL_ENCODE_PP` is set in the environment). Use `URL::Encode`; nothing is exported by default. `url_encode` escapes every byte except `A-Z a-z 0-9 - . _ ~` as `%XX`, a space as `+`; `url_decode` reverses it, and leaves a `%` that is not followed by two hex digits as it is. The `_utf8` variants take and return character strings, the others octets: an octet argument with a character above 255 croaks "Wide character in octet string". The `url_params_*` functions split on `&` and `;`, and `=` separates a name from its value; a pair without `=` has the value undef. With a true second argument, names and values are decoded as UTF-8. `url_params_flat` returns an array reference of names and values in order, `url_params_mixed` a hash reference whose repeated names hold an array reference of their values, `url_params_multi` a hash reference of array references, and `url_params_each` calls a code reference with each name and value. This is a native implementation of URL::Encode::XS 0.03's `XS.xs`; its `URL/Encode/XS.pm` is used unchanged. ## Synopsis ```perl use URL::Encode qw(url_encode_utf8 url_decode_utf8 url_params_mixed); my $q = url_encode_utf8("K\x{f6}ln & more"); # "K%C3%B6ln+%26+more" print url_decode_utf8($q), "\n"; # "Köln & more" my $p = url_params_mixed("a=1&b=2&a=3"); # { a => [1, 3], b => 2 } ``` ## Functions ### Encoding #### `url_decode` `url_decode($octets)`: the octets with `+` and the `%XX` escapes decoded. #### `url_decode_utf8` `url_decode_utf8($octets)`: `url_decode`, then the result decoded as UTF-8; croaks "Malformed UTF-8 in URL decoded string" when it is not. #### `url_encode` `url_encode($octets)`: every byte except `A-Z a-z 0-9 - . _ ~` as `%XX`, a space as `+`. #### `url_encode_utf8` `url_encode_utf8($string)`: the string encoded as UTF-8, then `url_encode`d. ### Query strings #### `url_params_flat` `url_params_flat($octets [, $utf8])`: an array reference of the names and values in order. #### `url_params_mixed` `url_params_mixed($octets [, $utf8])`: a hash reference; a name given more than once holds an array reference of its values. #### `url_params_multi` `url_params_multi($octets [, $utf8])`: a hash reference of array references of the values. #### `url_params_each` `url_params_each($octets, $callback [, $utf8])`: call `$callback` with each name and value; returns nothing.