URL::Encode(3pm)

💖 URL::Encode 💖

okay bestie, so this page is all about URL::Encode — the Perl module for encoding and decoding stuff in application/x-www-form-urlencoded encoding. it lives in the perl manual pages (section 3pm, user contributed perl docs, iykyk) and it's genuinely so useful. let's get into it 🦋

---

✨ SYNOPSIS ✨

like, here's the whole vibe at a glance:

$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]);

periodt. now the deets 💅

---

🌸 DESCRIPTION 🌸

This module provides functions to encode and decode strings into and from the application/x-www-form-urlencoded encoding. no cap, that's the whole job and it does it gorgeously.

So the application/x-www-form-urlencoded 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 % followed by the two hexadecimal digits representing that octet's numeric value. it's giving very precise, very demure 💜

And the unreserved character set? literally the VIP list, bestie:

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789
- . _ ~

uppercase letters, lowercase letters, decimal digits, hyphen, period, underscore, and tilde. everyone else is getting percent-encoded, sorry not sorry ✨

---

👑 FUNCTIONS 👑

🎀 url_decode

$octets = url_decode($octets);

Returns a decoded representation of the given URL-encoded $octets as an octet string. she un-scrambles it for you 🫶

🎀 url_decode_utf8

$string = url_decode_utf8($octets);

Returns a decoded representation of the given URL-encoded $octets in UTF-8 encoding as a character string. same energy, but make it UTF-8 💖

🎀 url_encode

$octets = url_encode($octets);

Returns a URL-encoded representation of the given $octets as an octet string. yes she's encoding the octets, exactly what it says 🌈

🎀 url_encode_utf8

$octets = url_encode_utf8($string);

Returns a URL-encoded representation of $string in UTF-8 encoding as an octet string. character string in, octet string out, iconic behavior ⭐

🎀 url_params_flat

$params = url_params_flat($octets);
$params = url_params_flat($octets, $utf8);

Parses a URL-encoded data set of name/value pairs from the given octets. Returns an ARRAY reference containing the URL-decoded name/value pairs in order. she keeps the order, she keeps it flat, she keeps it cute 😌

$params = url_params_flat('foo=A&foo=B&bar=C');
$params; # [ foo => 'A', foo => 'B', bar => 'C' ]

see how foo shows up twice? flat does not care, flat does not merge. queen of honesty 💅

🎀 url_params_mixed

$params = url_params_mixed($octets);
$params = url_params_mixed($octets, $utf8);

Parses a URL-encoded data set of name/value pairs from the given octets. Returns a HASH reference containing the URL-decoded name/value pairs. Multiple occurrences of a parameter will result in an ARRAY reference holding all the values for that parameter in order. so it's a hash, but when a name repeats you get an arrayref instead of a plain value — mixed, hence the name, she said what she said 🧚

$params = url_params_mixed('foo=A&foo=B&bar=C');
$params; # { foo => [ 'A', 'B' ], bar => 'C' }

bar only showed up once so it's just a plain string. foo got an arrayref. balance 💖

🎀 url_params_multi

$params = url_params_multi($octets);
$params = url_params_multi($octets, $utf8);

Parses a URL-encoded data set of name/value pairs from the given octets. Returns a HASH reference containing the URL-decoded name/value pairs. Values are stored in an ARRAY reference. every single value, arrayref, no exceptions. consistency is the vibe 🔥

$params = url_params_multi('foo=A&foo=B&bar=C');
$params; # { foo => [ 'A', 'B' ], bar => [ 'C' ] }

🎀 url_params_each

url_params_each($octets, $callback);
url_params_each($octets, $callback, $utf8);

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. you bring the callback, she brings the pairs, we all eat 🍓

$callback = sub {
    my ($name, $value) = @_;
};

url_params_each($octets, $callback);

---

🦋 EXPORTS 🦋

None by default. All functions can be exported using the ":all" tag or individually. so you can have all of them, but you have to ask nicely first 😭

---

💀 DIAGNOSTICS 💀

• (F) Usage: %s — Subroutine called with wrong number of arguments. bestie the arg count was wrong, she's calling you out.
• (F) Wide character in octet string
• (F) Malformed UTF-8 in URL-decoded octets

those (F) ones are fatal, okay? like, not a vibe, the program stops. be careful with your encodings 🫶

---

⚡ 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. so if you've got the XS version chilling in your install, she'll pick it up on her own, no config needed, main character energy 👑

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%              --

not the XS version absolutely demolishing the pure-perl one, we love to see it 🔥

---

🌈 SEE ALSO 🌈

• URL::Encode::XS — XS implementation of URL::Encode.
• CGI::Deurl::XS

---

🫶 SUPPORT 🫶

🐛 BUGS

Please report any bugs by email to bug-url-encode at rt.cpan.org, 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. so like, if something's broken, tell the system, the system will text you back, it's very thoughtful 💜

📦 SOURCE CODE

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<http://github.com/chansen/p5-url-encode>

git clone http://github.com/chansen/p5-url-encode

go clone it, go contribute, go be part of the story ✨

---

🎀 AUTHOR 🎀

Christian Hansen chansen@cpan.org

---

📜 COPYRIGHT 📜

Copyright 2011-2014 by Christian Hansen.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💖 tysm for reading, this was documented by perl v5.36.0 on 2022-11-19, and the page you just read is URL::Encode(3pm). now go encode something responsibly 🦋✨💅