URL::Encode::XS#

📦 std

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#

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_encoded.

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.