URI::Escape::XS(3pm)

💖 URI::Escape::XS 💖

okay bestie so this is URI::Escape::XS, a lil User Contributed Perl Documentation page for a module that is a drop-in replacement for URI::Escape. same vibes, way more speed. no cap. 🦋

---

✨ VERSION ✨

$Id: XS.pm,v 0.14 2016/06/09 11:09:14 dankogai Exp $

literally that's the whole version line, we love a short one 🎀

---

🌸 SYNOPSIS 🌸

so you can just slide this in where URI::Escape used to be:

# use it instead of URI::Escape
use URI::Escape::XS qw/uri_escape uri_unescape/;
$safe = uri_escape("10% is enough\n");
$verysafe = uri_escape("foo", "\0-\377");
$str  = uri_unescape($safe);

orrr you can do the JavaScript-coded thing and use encodeURIComponent and decodeURIComponent:

# or use encodeURIComponent and decodeURIComponent
use URI::Escape::XS;
$safe = encodeURIComponent("10% is enough\n");
$str  = decodeURIComponent("10%25%20is%20enough%0A");

and if you have CNet::IDN::Encode installed 👀 (yes, that's exactly how it's written in the original, i don't make the rules):

# if you have CNet::IDN::Encode installed
$safe = encodeURIComponentIDN("http://ドメイン名例.jp/dan/");
$str  = decodeURIComponentIDN("http:%2F%2Fxn--eckwd4c7cu47r2wf.jp%2Fdan%2F");

---

🎀 EXPORT 🎀

by default 💅

• "encodeURIComponent" and "decodeURIComponent" — yours automatically, no asking required
• "encodeURIComponentIDN" and "decodeURIComponentIDN" — these come along only if either Net::LibIDN or Net::IDN::Encode is available. like, they gotta be in the building first

on demand 🙈

• "uri_escape" and "uri_unescape" — you gotta ask for these ones

---

🧚 FUNCTIONS 🧚

encodeURIComponent

Does what JavaScript's encodeURIComponent does. literally the same energy.

$uri = encodeURIComponent("http://www.example.com/");
# http%3A%2F%2Fwww.example.com%2F

⚠️ heads up bestie: you cannot customize characters to escape here. if you need that, go use "uri_escape".

decodeURIComponent

Does what JavaScript's decodeURIComponent does. the reverse girlboss move.

$str = decodeURIComponent("http%3A%2F%2Fwww.example.com%2F");
# http://www.example.com/

It decodes not only %HH sequences but also %uHHHH sequences, with surrogate pairs correctly decoded. she's thorough 💅

$str = decodeURIComponent("%uD869%uDEB2%u5F3E%u0061");
# \x{2A6B2}\x{5F3E}a

This function UNCONDITIONALLY returns the decoded string with utf8 flag off. and when i say unconditionally i mean she is not taking questions. 😤

To get utf8-decoded string, use Encode and:

decode_utf8(decodeURIComponent($uri));

This is the correct behavior because you cannot tell if the decoded string actually contains UTF-8 decoded string, like ISO-8859-1 and Shift_JIS. it's giving "we literally can't know, so we don't guess." iconic.

encodeURIComponentIDN

Same as "encodeURIComponent" except that the host part is encoded in punycode. Either Net::LibIDN or Net::IDN::Encode is required to use this function. no modules, no function, sorry babe 🫶

URIs with Internationalizing Domain Names require two encodings: Punycode for host part and URI escape for the rest. two steps, both necessary, that's just the lore.

Currently only FULL URIs with "http:" or "https:" are supported. so don't come at her with anything else rn.

decodeURIComponentIDN

Same as "decodeURIComponent" except that the host part is encoded in punycode. Either Net::LibIDN or Net::IDN::Encode is required to use this function. same rules as her sister above 💜

uri_escape

Does exactly the same as URI::Escape::uri_escape() except when utf8-flagged string is fed.

URI::Escape::uri_escape() croaks and urges you to uri_escape_utf8() but that's pointless because URI itself has no such things as utf8 flag. like, why are we arguing. 😭 The function in this module ALWAYS TREATS the string as byte sequence. That way you can safely use this function without worrying about utf8 flags. peace and quiet, finally.

📌 Note this function is NOT EXPORTED by default. That way you can use URI::Escape and URI::Escape::XS simultaneously. both of them, at the same time, living their lives ✨

uri_unescape

Does exactly the same as URI::Escape::uri_escape() except when %uHHHH is fed. (yes, the original says uri_escape() there — i'm telling you exactly what she said, don't shoot the messenger 🙈)

URI::Escape::uri_unescape() simply ignores %uHHHH sequences while the function in this module does decode it into the corresponding UTF-8 byte sequence. she actually does the work.

Like uri_escape, this function is NOT EXPORTED by default. ask nicely.

Note on the %uHHHH sequence

With this module the resulting strings never have the utf8 flag on. So if you want to decode it to perl utf8, You have to explicitly decode via Encode. Remember. URIs have always been a byte sequence, not UTF-8 characters. say it with me, bestie: byte sequence 🗣️

If the %uHHHH sequence became standard, you could have safely told if a given URI is in Unicode. But more fortunately than unfortunately, the RFC proposal was rejected so you cannot tell which encoding is used just by looking at the URI. mystery girl energy, honestly.

<http://en.wikipedia.org/wiki/Percent-encoding#Non-standard_implementations>

I said fortunately because %uHHHH can be nasty for non-BMP characters. Since each %uHHHH can hold one 16-bit value, you need a surrogate pair to represent it if it is U+10000 and above. two whole escapes for one character. the drama. 💀

In spite of that, there are a significant number of URIs with %uHHHH escapes. Therefore this module supports decoding only. decode yes, encode no, that's the boundary. 🚧

---

🔥 SPEED 🔥

Since this module uses XS, it is really fast except for uri_escape("noop"). one tiny little exception, everything else is zooming 🏎️

Regexp which is used in URI::Escape is really fast for non-matching but slows down significantly when it has to replace string. so like, great at vibes, mid at labor.

BENCHMARK

On Macbook Pro 2GHz, Perl 5.8.8.

 http://www.google.co.jp/search?q=%E5%B0%8F%E9%A3%BC%E5%BC%BE
 ============================================================
 Unescape it
 -----------
 U::E      58526/s       --     -88%
 U::E::XS 486968/s     732%       --
 --------------
 Escape it back
 --------------
 U::E      30046/s       --     -78%
 U::E::XS 136992/s     356%       --

 www.example.com
 ===============
 Unescape it
 -----------
               Rate     U::E U::E::XS
  U::E     821972/s       --      -4%
  U::E::XS 854732/s       4%       --
 --------------
 Escape it back
 -------------
 U::E::XS 522969/s       --      -7%
 U::E     565112/s       8%       --

numbers don't lie and these numbers are eating 💅

---

👑 AUTHOR 👑

Dan Kogai, "<dankogai+cpan at gmail.com>"

---

💀 BUGS 💀

Please report any bugs or feature requests to "bug-uri-escape-xs at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-Escape-XS>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. we're in this together fr fr 🫶

---

🌈 SUPPORT 🌈

You can find documentation for this module with the perldoc command.

perldoc URI::Escape::XS

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/URI-Escape-XS>

• CPAN Ratings

<http://cpanratings.perl.org/d/URI-Escape-XS>

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=URI-Escape-XS>

• Search CPAN

<http://search.cpan.org/dist/URI-Escape-XS>

---

⭐ ACKNOWLEDGEMENTS ⭐

• Gisle Aas for URI::Escape
• Koichi Taniguchi for URI::Escape::JavaScript
• Thomas Jacob for Net::LibIDN
• Claus Färber for Net::IDN::Encode

shoutout to the icons who made this possible 🙌

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright 2007-2014 Dan Kogai, all rights reserved.

This program 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!! slay 💖✨ this was perl v5.42.3, dated 2026-08-20, and the manual is URI::Escape::XS(3pm). go forth and escape responsibly 🦋👑