.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "URL::Encode 3pm"
.TH URL::Encode 3pm "2018-09-02" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
URL::Encode \- Encoding and decoding of "application/x\-www\-form\-urlencoded" encoding.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    $octets = url_decode($octets);
\&    $string = url_decode_utf8($octets);
\&    
\&    $octets = url_encode($octets);
\&    $octets = url_encode_utf8($string);
\&    
\&    $params = url_params_flat($octets [, $utf8 = false]);
\&    $params = url_params_mixed($octets [, $utf8 = false]);
\&    $params = url_params_multi($octets [, $utf8 = false]);
\&              url_params_each($octets, $callback [, $utf8 = false]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functions to encode and decode strings into and from the 
\&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR encoding.
.PP
The \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR format encodes a ordered data 
sets of pairs consisting of a name and a value, with pairs separated by
ampersand or semicolon and names and values separated by the equal sign.
Space characters are replaced with plus sign and any characters not in 
the unreserved character set is encoded using the percent-encoding scheme 
also used for resource identifiers. A percent-encoded octet is encoded as 
a character triplet, consisting of the percent character \*(L"%\*(R" followed by 
the two hexadecimal digits representing that octet's numeric value.
.PP
The unreserved character set includes the uppercase and lowercase letters, 
decimal digits, hyphen, period, underscore, and tilde.
.PP
.Vb 4
\&    ABCDEFGHIJKLMNOPQRSTUVWXYZ
\&    abcdefghijklmnopqrstuvwxyz
\&    0123456789
\&    \- . _ ~
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "url_decode"
.IX Subsection "url_decode"
.Vb 1
\&    $octets = url_decode($octets);
.Ve
.PP
Returns a decoded representation of the given URL-encoded \f(CW$octets\fR as an 
octet string.
.SS "url_decode_utf8"
.IX Subsection "url_decode_utf8"
.Vb 1
\&    $string = url_decode_utf8($octets);
.Ve
.PP
Returns a decoded representation of the given URL-encoded \f(CW$octets\fR in
\&\s-1UTF\-8\s0 encoding as a character string.
.SS "url_encode"
.IX Subsection "url_encode"
.Vb 1
\&    $octets = url_encode($octets);
.Ve
.PP
Returns a URL-encoded representation of the given \f(CW$octets\fR as an octet 
string.
.SS "url_encode_utf8"
.IX Subsection "url_encode_utf8"
.Vb 1
\&    $octets = url_encode_utf8($string);
.Ve
.PP
Returns a URL-encoded representation of \f(CW$string\fR in \s-1UTF\-8\s0 encoding as an 
octet string.
.SS "url_params_flat"
.IX Subsection "url_params_flat"
.Vb 2
\&    $params = url_params_flat($octets);
\&    $params = url_params_flat($octets, $utf8);
.Ve
.PP
Parses a URL-encoded data set of name/value pairs from the given octets. 
Returns an \s-1ARRAY\s0 reference containing the URL-decoded name/value pairs in order.
.PP
.Vb 2
\&    $params = url_params_flat(\*(Aqfoo=A&foo=B&bar=C\*(Aq);
\&    $params; # [ foo => \*(AqA\*(Aq, foo => \*(AqB\*(Aq, bar => \*(AqC\*(Aq ]
.Ve
.SS "url_params_mixed"
.IX Subsection "url_params_mixed"
.Vb 2
\&    $params = url_params_mixed($octets);
\&    $params = url_params_mixed($octets, $utf8);
.Ve
.PP
Parses a URL-encoded data set of name/value pairs from the given octets. 
Returns a \s-1HASH\s0 reference containing the URL-decoded name/value pairs. Multiple 
occurrences of a parameter will result in an \s-1ARRAY\s0 reference holding all 
the values for that parameter in order.
.PP
.Vb 2
\&    $params = url_params_mixed(\*(Aqfoo=A&foo=B&bar=C\*(Aq);
\&    $params; # { foo => [ \*(AqA\*(Aq, \*(AqB\*(Aq ], bar => \*(AqC\*(Aq }
.Ve
.SS "url_params_multi"
.IX Subsection "url_params_multi"
.Vb 2
\&    $params = url_params_multi($octets);
\&    $params = url_params_multi($octets, $utf8);
.Ve
.PP
Parses a URL-encoded data set of name/value pairs from the given octets. 
Returns a \s-1HASH\s0 reference containing the URL-decoded name/value pairs. Values 
are stored in an \s-1ARRAY\s0 reference.
.PP
.Vb 2
\&    $params = url_params_multi(\*(Aqfoo=A&foo=B&bar=C\*(Aq);
\&    $params; # { foo => [ \*(AqA\*(Aq, \*(AqB\*(Aq ], bar => [ \*(AqC\*(Aq ] }
.Ve
.SS "url_params_each"
.IX Subsection "url_params_each"
.Vb 2
\&    url_params_each($octets, $callback);
\&    url_params_each($octets, $callback, $utf8);
.Ve
.PP
Parses a URL-encoded data set of name/value pairs from the given octets. 
Invokes the given callback for each URL-decoded name/value pair.
.PP
.Vb 3
\&    $callback = sub {
\&        my ($name, $value) = @_;
\&    };
\&    
\&    url_params_each($octets, $callback);
.Ve
.SH "EXPORTS"
.IX Header "EXPORTS"
None by default. All functions can be exported using the \f(CW\*(C`:all\*(C'\fR tag or individually.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "\fB(F)\fR Usage: %s" 4
.el .IP "\fB(F)\fR Usage: \f(CW%s\fR" 4
.IX Item "(F) Usage: %s"
Subroutine called with wrong number of arguments.
.IP "\fB(F)\fR Wide character in octet string" 4
.IX Item "(F) Wide character in octet string"
.PD 0
.IP "\fB(F)\fR Malformed \s-1UTF\-8\s0 in URL-decoded octets" 4
.IX Item "(F) Malformed UTF-8 in URL-decoded octets"
.PD
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
The URL::Encode::XS module provides faster C/XS implementations of 
the functions found in this module. This module will automatically use 
URL::Encode::XS if it's installed.
.PP
.Vb 1
\&    Benchmarking url_decode() PP vs XS:
\&
\&            Rate    PP    XS
\&    PP  507520/s    \-\-  \-92%
\&    XS 6389812/s 1159%    \-\-
\&
\&    Benchmarking url_encode() PP vs XS:
\&
\&            Rate    PP    XS
\&    PP  119866/s    \-\-  \-98%
\&    XS 7214089/s 5918%    \-\-
\&
\&    Benchmarking url_params_mixed() PP vs XS:
\&
\&          Rate    PP    XS
\&    PP  4450/s    \-\-  \-95%
\&    XS 95015/s 2035%    \-\-
\&
\&    Benchmarking URL::Encode::XS vs CGI::Deurl::XS
\&
\&                       Rate  CGI::Deurl::XS URL::Encode::XS
\&    CGI::Deurl::XS  51932/s              \-\-            \-48%
\&    URL::Encode::XS 99444/s             91%              \-\-
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "URL::Encode::XS" 4
.IX Item "URL::Encode::XS"
\&\s-1XS\s0 implementation of \f(CW\*(C`URL::Encode\*(C'\fR.
.IP "CGI::Deurl::XS" 4
.IX Item "CGI::Deurl::XS"
.SH "SUPPORT"
.IX Header "SUPPORT"
.SS "\s-1BUGS\s0"
.IX Subsection "BUGS"
Please report any bugs by email to \f(CW\*(C`bug\-url\-encode at rt.cpan.org\*(C'\fR, or 
through the web interface at <http://rt.cpan.org/Public/Dist/Display.html?Name=URL\-Encode>. 
You will be automatically notified of any progress on the request by the system.
.SS "\s-1SOURCE CODE\s0"
.IX Subsection "SOURCE CODE"
This is open source software. The code repository is available for public 
review and contribution under the terms of the license.
.PP
<http://github.com/chansen/p5\-url\-encode>
.PP
.Vb 1
\&    git clone http://github.com/chansen/p5\-url\-encode
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Christian Hansen \f(CW\*(C`chansen@cpan.org\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2011\-2014 by Christian Hansen.
.PP
This library is free software; you can redistribute it and/or modify 
it under the same terms as Perl itself.