Locale::Recode(3)

💅 Locale::Recode(3) — Object-Oriented Portable Charset Conversion

okay bestie, so this is a page from the User Contributed Perl Documentation collection, and it's literally about converting text between charsets in a way that just works everywhere. let's get into it 🎀

---

✨ SYNOPSIS ✨

use Locale::Recode;

$cd = Locale::Recode->new (from => 'UTF-8',
                           to   => 'ISO-8859-1');

die $cd->getError if $cd->getError;

$cd->recode ($text) or die $cd->getError;

$mime_name = Locale::Recode->resolveAlias ('latin-1');

$supported = Locale::Recode->getSupported;

$complete = Locale::Recode->getCharsets;

---

🌸 DESCRIPTION 🌸

This module gives you routines that convert textual data from one codeset to another, in a portable way. no cap, that's the whole vibe. 🦋

Fun lore drop: this module got started before Encode(3) was even written. Its main purpose today is to still do charset conversion even when Encode(3) isn't available on the system. It should also work on older Perl versions that don't have Unicode support at all. iconic, honestly. 👑

Internally, Locale::Recode(3) will use Encode(3) whenever it possibly can — that gives you a faster conversion and a way wider range of supported charsets — and it will only fall back to the pure Perl implementation when Encode(3) isn't available or doesn't support a particular charset that Locale::Recode(3) does. main character energy: uses the fast path when it can, keeps its own backup plan. 💅

Locale::Recode(3) is part of libintl-perl, and ngl its real main purpose is to implement a portable charset conversion framework for the message translation facilities described over in Locale::TextDomain(3). 🫶

---

🧚 CONSTRUCTOR 🧚

The constructor new() requires two named arguments:

• from — the encoding of the original data. case doesn't matter at all, and aliases get resolved for you. 💖
• to — the target encoding. again, case doesn't matter, and aliases are resolved. 💖

The constructor will never fail. 😭 In case of an error, the object's internal state is set to bad and it will flat-out refuse to do any conversions. You can ask why it's mad with the method getError().

---

🎀 OBJECT METHODS 🎀

These are the object methods you've got, bestie:

• recode (STRING) — converts STRING from the source encoding into the destination encoding. on success you get a truth value, otherwise false. if it fails, hit up getError() to find out the reason. 🔥
• getError — returns either false if the object isn't in an error state, or an error message. simple as that. ✨

---

🌈 CLASS METHODS 🌈

The object also serves up some extra class methods:

• getSupported — returns a reference to a list of all supported charsets. ⚠️ heads up: this may implicitly load additional Encode(3) conversions like Encode::HanExtra(3), which can put considerable load on your system. So the method is not intended for regular use — it's for getting / displaying a list of available encodings once in a while. also: the members of the list are all converted to uppercase! 📣
• getCharsets — same energy as getSupported() but it also returns all available aliases. 💜

---

🦋 SUPPORTED CHARSETS 🦋

The range of supported charsets is system-dependent, so your mileage may literally vary. that said, these somewhat special charsets are always available:

⭐ UTF-8

UTF-8 is available independently of your Perl version. 🎉 For Perl 5.6 or better, or when Encode(3) is present, conversions aren't done in Perl — they use the interfaces those facilities provide, which are written in C, hence much faster.

Encoding data into UTF-8 is fast, even when it's done in Perl. Decoding it in Perl may become quite slow though 😭. So if you frequently have to decode UTF-8 with Locale::Recode, you'll probably want to make sure you do that with Perl 5.6 or beter, or install Encode(3) to speed things up. 🏃‍♀️💨

⭐ INTERNAL

UTF-8 is fast to write but hard to read for applications. It's therefore not the worst for internal string representation, but honestly it's not far from that either. 🙈 Locale::Recode(3) stores strings internally as a reference to an array of integer values, like most programming languages do (Perl is the exception here, bestie) — trading memory for performance. 💀

The integer values are the UCS-4 codes of the characters, in host byte order.

The encoding INTERNAL is directly available via Locale::Recode(3), but of course you should not really use it for data exchange — unless you know exactly what you're doing. 👀

---

Locale::Recode(3) also has native support for a plethora of other encodings, most of them 8-bit encodings that are fast to decode. that includes most encodings used on popular micros, like the ISO-8859-* series of encodings, most Windows-* encodings (also known as CP*), Macintosh, Atari, etc. etc. etc. 🌸

---

💜 NAMES AND ALIASES 💜

Each charset (resp. encoding) is available internally under a unique name. Whenever the info was available, the preferred MIME name (see <http://www.iana.org/assignments/character-sets/>) was chosen as the internal name. 🎯

Alias handling is quite strict. The module does not make wild guesses at what you mean — like, "What's the meaning of the acronym JIS" is a valid alias for 7bit-jis in Encode(3)... and that's exactly the kind of chaos this module is not about 😤 — it aims at providing common aliases only. The same applies to so-called aliases that are really mistakes, like utf8 for UTF-8. no thank you. 🙅‍♀️

The module knows all aliases listed with the IANA character set registry (<http://www.iana.org/assignments/character-sets/>), plus those known to libiconv version 1.8, and a bunch of additional ones. 💐

---

🌟 CONVERSION TABLES 🌟

The conversion tables were taken from official sources like the IANA or the Unicode Consortium, from Bruno Haible's libiconv, or from the sources of the GNU libc — and the regression tests for libintl-perl will check for conformance here. 📋✨

For some encodings, this data differs from Encode(3)'s data, which would cause these tests to fail. In those cases the module will not invoke the Encode(3) methods — it falls back to the internal implementation for the sake of consistency. consistency queen. 👑

The few encodings that are affected are so simple that you won't experience any real performance penalty, unless you convert large chunks of data. But the package isn't really intended for that kind of use anyway, and since Encode(3) is relatively new, the author rather thinks those differences are bugs in Encode that'll be fixed soon. 🤷‍♀️

---

💀 BUGS 💀

• The module should provide fall back conversions for other Unicode encoding schemes like UCS-2, UCS-4 (big- and little-endian). it does not. 😭
• The pure Perl UTF-8 decoder will not always handle corrupt UTF-8 correctly, especially at the end and at the beginning of the string. This is not likely to be fixed, since the module's intention is not to be a consistency checker for UTF-8 data. so like... don't come for it. 🙈

---

👑 AUTHOR 👑

Copyright (C) 2002-2017 Guido Flohr <http://www.guido-flohr.net/> (<mailto:guido.flohr@cantanea.com>), all rights reserved. See the source code for details!code for details!

---

🔍 SEE ALSO 🔍

Encode(3), iconv(3), iconv(1), recode(1), perl(1)

---

that's the whole page, bestie 💅 this one's from perl v5.42.0, dated 2025-01-22 — go convert some charsets and slay ✨🎀