| 1 |
NAME |
| 2 |
URL::Encode - Encoding and decoding of |
| 3 |
"application/x-www-form-urlencoded" encoding. |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
$octets = url_decode($octets); |
| 7 |
$string = url_decode_utf8($octets); |
| 8 |
|
| 9 |
$octets = url_encode($octets); |
| 10 |
$octets = url_encode_utf8($string); |
| 11 |
|
| 12 |
$params = url_params_flat($octets [, $utf8 = false]); |
| 13 |
$params = url_params_mixed($octets [, $utf8 = false]); |
| 14 |
$params = url_params_multi($octets [, $utf8 = false]); |
| 15 |
url_params_each($octets, $callback [, $utf8 = false]); |
| 16 |
|
| 17 |
DESCRIPTION |
| 18 |
This module provides functions to encode and decode strings into and |
| 19 |
from the "application/x-www-form-urlencoded" encoding. |
| 20 |
|
| 21 |
The "application/x-www-form-urlencoded" format encodes a ordered data |
| 22 |
sets of pairs consisting of a name and a value, with pairs seperated by |
| 23 |
ampersand or semicolon and names and values seperated by the equal sign. |
| 24 |
Space characters are replaced with plus sign and any characters not in |
| 25 |
the unreserved character set is encoded using the percent-encoding |
| 26 |
scheme also used for resource identifiers. A percent-encoded octet is |
| 27 |
encoded as a character triplet, consisting of the percent character "%" |
| 28 |
followed by the two hexadecimal digits representing that octet's numeric |
| 29 |
value. |
| 30 |
|
| 31 |
The unreserved character set includes the uppercase and lowercase |
| 32 |
letters, decimal digits, hyphen, period, underscore, and tilde. |
| 33 |
|
| 34 |
ABCDEFGHIJKLMNOPQRSTUVWXYZ |
| 35 |
abcdefghijklmnopqrstuvwxyz |
| 36 |
0123456789 |
| 37 |
- . _ ~ |
| 38 |
|
| 39 |
FUNCTIONS |
| 40 |
url_decode |
| 41 |
$octets = url_decode($octets); |
| 42 |
|
| 43 |
Returns a decoded representation of the given URL-encoded $octets as an |
| 44 |
octet string. |
| 45 |
|
| 46 |
url_decode_utf8 |
| 47 |
$string = url_decode_utf8($octets); |
| 48 |
|
| 49 |
Returns a decoded representation of the given URL-encoded $octets in |
| 50 |
UTF-8 encoding as a character string. |
| 51 |
|
| 52 |
url_encode |
| 53 |
$octets = url_encode($octets); |
| 54 |
|
| 55 |
Returns a URL-encoded representation of the given $octets as an octet |
| 56 |
string. |
| 57 |
|
| 58 |
url_encode_utf8 |
| 59 |
$octets = url_encode_utf8($string); |
| 60 |
|
| 61 |
Returns a URL-encoded representation of $string in UTF-8 encoding as an |
| 62 |
octet string. |
| 63 |
|
| 64 |
url_params_flat |
| 65 |
$params = url_params_flat($octets); |
| 66 |
$params = url_params_flat($octets, $utf8); |
| 67 |
|
| 68 |
Parses a URL-encoded data set of name/value pairs from the given octets. |
| 69 |
Returns an ARRAY reference containing the URL-decoded name/value pairs |
| 70 |
in order. |
| 71 |
|
| 72 |
$params = url_params_flat('foo=A&foo=B&bar=C'); |
| 73 |
$params; # [ foo => 'A', foo => 'B', bar => 'C' ] |
| 74 |
|
| 75 |
url_params_mixed |
| 76 |
$params = url_params_mixed($octets); |
| 77 |
$params = url_params_mixed($octets, $utf8); |
| 78 |
|
| 79 |
Parses a URL-encoded data set of name/value pairs from the given octets. |
| 80 |
Returns a HASH reference containing the URL-decoded name/value pairs. |
| 81 |
Multiple occurrences of a parameter will result in an ARRAY reference |
| 82 |
holding all the values for that parameter in order. |
| 83 |
|
| 84 |
$params = url_params_mixed('foo=A&foo=B&bar=C'); |
| 85 |
$params; # { foo => [ 'A', 'B' ], bar => 'C' } |
| 86 |
|
| 87 |
url_params_multi |
| 88 |
$params = url_params_multi($octets); |
| 89 |
$params = url_params_multi($octets, $utf8); |
| 90 |
|
| 91 |
Parses a URL-encoded data set of name/value pairs from the given octets. |
| 92 |
Returns a HASH reference containing the URL-decoded name/value pairs. |
| 93 |
Values are stored in an ARRAY reference. |
| 94 |
|
| 95 |
$params = url_params_multi('foo=A&foo=B&bar=C'); |
| 96 |
$params; # { foo => [ 'A', 'B' ], bar => [ 'C' ] } |
| 97 |
|
| 98 |
url_params_each |
| 99 |
url_params_each($octets, $callback); |
| 100 |
url_params_each($octets, $callback, $utf8); |
| 101 |
|
| 102 |
Parses a URL-encoded data set of name/value pairs from the given octets. |
| 103 |
Invokes the given callback for each URL-decoded name/value pair. |
| 104 |
|
| 105 |
$callback = sub { |
| 106 |
my ($name, $value) = @_; |
| 107 |
}; |
| 108 |
|
| 109 |
url_params_each($octets, $callback); |
| 110 |
|
| 111 |
EXPORTS |
| 112 |
None by default. All functions can be exported using the ":all" tag or |
| 113 |
individually. |
| 114 |
|
| 115 |
DIAGNOSTICS |
| 116 |
(F) Usage: %s |
| 117 |
Subroutine called with wrong number of arguments. |
| 118 |
|
| 119 |
(F) Wide character in octet string |
| 120 |
(F) Malformed UTF-8 in URL-decoded octets |
| 121 |
|
| 122 |
PERFORMANCE |
| 123 |
The URL::Encode::XS module provides faster C/XS implementations of the |
| 124 |
functions found in this module. This module will automatically use |
| 125 |
URL::Encode::XS if it's installed. |
| 126 |
|
| 127 |
Benchmarking url_decode() PP vs XS: |
| 128 |
|
| 129 |
Rate PP XS |
| 130 |
PP 507520/s -- -92% |
| 131 |
XS 6389812/s 1159% -- |
| 132 |
|
| 133 |
Benchmarking url_encode() PP vs XS: |
| 134 |
|
| 135 |
Rate PP XS |
| 136 |
PP 119866/s -- -98% |
| 137 |
XS 7214089/s 5918% -- |
| 138 |
|
| 139 |
Benchmarking url_params_mixed() PP vs XS: |
| 140 |
|
| 141 |
Rate PP XS |
| 142 |
PP 4450/s -- -95% |
| 143 |
XS 95015/s 2035% -- |
| 144 |
|
| 145 |
Benchmarking URL::Encode::XS vs CGI::Deurl::XS |
| 146 |
|
| 147 |
Rate CGI::Deurl::XS URL::Encode::XS |
| 148 |
CGI::Deurl::XS 51932/s -- -48% |
| 149 |
URL::Encode::XS 99444/s 91% -- |
| 150 |
|
| 151 |
SEE ALSO |
| 152 |
URL::Encode::XS |
| 153 |
XS implementation of "URL::Encode". |
| 154 |
|
| 155 |
CGI::Deurl::XS |
| 156 |
|
| 157 |
SUPPORT |
| 158 |
BUGS |
| 159 |
Please report any bugs by email to "bug-url-encode at rt.cpan.org", or |
| 160 |
through the web interface at |
| 161 |
<http://rt.cpan.org/Public/Dist/Display.html?Name=URL-Encode>. You will |
| 162 |
be automatically notified of any progress on the request by the system. |
| 163 |
|
| 164 |
SOURCE CODE |
| 165 |
This is open source software. The code repository is available for |
| 166 |
public review and contribution under the terms of the license. |
| 167 |
|
| 168 |
<http://github.com/chansen/p5-url-encode> |
| 169 |
|
| 170 |
git clone http://github.com/chansen/p5-url-encode |
| 171 |
|
| 172 |
AUTHOR |
| 173 |
Christian Hansen "[email protected]" |
| 174 |
|
| 175 |
COPYRIGHT |
| 176 |
Copyright 2011-2014 by Christian Hansen. |
| 177 |
|
| 178 |
This library is free software; you can redistribute it and/or modify it |
| 179 |
under the same terms as Perl itself. |
| 180 |
|