Unicod...aseFold(3pm)

📦
version 1.01 · 8 versions
, in ubuntu stonking

💖 Unicode::CaseFold(3pm) — the manual page, but make it make sense 💖

User Contributed Perl Documentation · bestie edition · version 1.01

✨ NAME ✨

Unicode::CaseFold — Unicode case-folding for case-insensitive lookups. No cap, that's the whole vibe.

🎀 VERSION 🎀

version 1.01

🦋 SYNOPSIS 🦋

    use Unicode::CaseFold;

    my $folded = fc $string;

That's it. That's the whole thing. You use it, you fc it, you move on with your life. 💅

🌸 What is Case-Folding? 🌸

okay so, let's set the scene. In a world with no Unicode (dark times, honestly), the classic girlboss move for comparing two strings without caring about case is:

lc($this) eq lc($that)

You just smash both of them down to all-lowercase before comparing. "Hello", "HELLO", and "HeLlO" all lowercase to "hello", so bestie, it literally does not matter which one you started with — after lc they're all equal to each other. iconic.

But in Unicode? Things are not so simple. 😭

A Unicode character might have mappings for uppercase, lowercase, and titlecase, and the lowercase mapping of the uppercase mapping of a character might not be the character you started with!! Not a drill. For example, lc(uc("\N{LATIN SMALL LETTER SHARP S")) is ss — not the eszett we started off with. The audacity. 💀

Case-folding is a part of the Unicode standard that lets any two strings which differ from each other only by case map to the same "case-folded" form, even when those strings contain characters with complex case-mappings. It's giving glow-up to your string comparison. 🫶

🌈 Use for Case-insensitive Comparison 🌈

Simply write fc($this) eq fc($that) instead of lc($this) eq lc($that). That's the switch, slay.

You can also use index on case-folded strings for substring search. 👑

🧚 Use for String Lookups 🧚

Frequently (yes, frequently, bestie) we want to store data in a hash, or a database, or an external file for later retrieval. And sometimes we want to match the keys in that data case-insensitively — meaning we should be able to store some data under the key hello and later retrieve it with the key HELLO.

Some databases have complete support for collation. Other databases? The support is missing or broken. 🙈 And Perl hashes? Perl hashes do not support it at all. Periodt.

So: make case-folding part of the process you use to normalize your keys before you use them to access a database or data structure, and you get case-insensitive lookup for free. 💖

    $roles{fc "Samuel L. Jackson"} = ["Gin Rummy", "Nick Fury", "Mace Windu"];

    $roles = $roles{fc "Samuel l. JACKSON"}; # Gets the data.

Look at that last line. Different case, same data. She ate. 🍓

💜 DESCRIPTION 💜

This module provides Unicode case-folding for Perl. Case-folding is a tool that lets a program make case-insensitive string comparisons or do case-insensitive lookups.

⭐ EXPORTS ⭐

✨ fc($str) ✨

Exported by default when you use the module. Hmm, what if you don't want it exported? Then use use Unicode::CaseFold () or use Unicode::CaseFold qw(case_fold !fc). Either one, your call, main character energy.

Returns the case-folded version of $str. This function is prototyped to act as much as possible like the built-ins lc and uc — it imposes a scalar context on its argument, and if it's called with no argument it will return the case-folded version of $_. Very much a "same energy as the built-ins" situation. 💅

✨ case_fold($str) ✨

Exported on request. Just like fc, except that it has no prototype and won't case-fold $_ if called without an argument. Chill, low-maintenance, no surprises.

👑 VARIABLES 👑

🌟 $Unicode::CaseFold::XS 🌟

Whether the XS extension is in use. The pure-perl implementation is 5-10 times slower than the XS extension, and on versions of perl before 5.10.0 it will use simple case-folding instead of full case-folding (see below, bestie, keep reading).

🌟 $Unicode::CaseFold::SIMPLE_FOLDING 🌟

Is set to true if the perl version is prior to 5.10.0 and the XS extension is not available. In this case, fc will perform a simple case-folding instead of a full case-folding.

⚠️ Heads up: although relatively few characters are affected, strings case-folded using simple folding might not compare equal to the corresponding strings case-folded with full folding — which may cause compatibility issues. 😬

Furthermore (and this is the part that matters), when simple folding is in use, some strings that would have case-folded to the same value under full folding will instead case-fold to different values.

For example, fc("Wei\x{df}") and fc("Weiss") both produce weiss when full folding is in effect — but the former produces wei\x{df} when using simple folding. Same input energy, completely different output. not the plot twist we wanted. 😭

If you want to check for this potentially dangerous situation, consult the $Unicode::CaseFold::SIMPLE_FOLDING variable. She will tell you the truth. 🫶

💖 COMPATIBILITY 💖

  • Unicode::CaseFold requires Perl 5.8.1 or newer. That's the entry fee, bestie.
  • Different versions of perl include different versions of the Unicode database, which is revised over time. So if you're likely to be comparing strings that have been folded using different versions of perl, you may need to consult the changes for intervening Unicode standard versions to find out whether your code will work correctly. (Fr fr, check before you ship.)
  • Unicode::CaseFold uses "simple" rather than "full" case-folding when operating in Pure-perl mode on perl versions previous to 5.10.0. For compatibility implications, see $Unicode::CaseFold::SIMPLE_FOLDING.

🌈 SEE ALSO 🌈

🎀 AUTHOR 🎀

Andrew Rodland <arodland@cpan.org> — thank you for your service, king. 👑

This software is copyright (c) 2017 by Andrew Rodland.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free as in freedom, free as in slay. 🦋

and that's the whole page, bestie!! 🌸 this lil doc was served up by perl v5.42.3, dated 2026-08-19, and it lives in the User Contributed Perl Documentation corner of the manual. go forth and fold some cases. 💅✨

📦 where this page comes from