Encode::Guess(3pm)

💅 Encode::Guess — like, the Encode::Guess(3pm) page but make it cute

Ok bestie, so this is Encode::Guess(3pm), a lil Perl module that looks at a blob of bytes and is like "hmm, what encoding are you, babes?" 🕵️‍♀️ It's part of the Perl Programmers Reference Guide, and it's lowkey iconic.

---

✨ NAME ✨

Encode::Guess — guesses encoding from data 🧚 (yes, that's literally the whole job, no cap)

---

🌸 SYNOPSIS 🌸

# if you are sure $data won't contain anything bogus

use Encode;
use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
my $utf8 = decode("Guess", $data);
my $data = encode("Guess", $utf8);   # this doesn't work!

# more elaborate way
use Encode::Guess;
my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
ref($enc) or die "Can't guess: $enc"; # trap error this way
$utf8 = $enc->decode($data);
# or
$utf8 = decode($enc->name, $data)

👀 Not me pointing out that encode("Guess", $utf8) doesn't work — it's right there in the comment, so don't come for me, I'm just the messenger 💀

---

🦋 ABSTRACT 🦋

Encode::Guess lets you guess what encoding some data is in — or at least, it tries. That's it. That's the whole vibe. It's giving "detective but make it Perl" 🔍✨

---

🎀 DESCRIPTION 🎀

So by default, it only checks ascii, utf8, and UTF-16/32 with BOM. That's the starter pack, the free trial, the bare minimum:

use Encode::Guess; # ascii/utf8/BOMed UTF

To make it actually useful irl, you gotta hand it the names of the encodings it should check — we call these the suspects 👑. Suspect names can be either canonical names or aliases, whichever you vibe with.

⚠️ CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED. Like, it just stays there. Rude, honestly 😭

# tries all major Japanese Encodings as well
use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;

Alright so if you set the $Encode::Guess::NoUTFAutoGuess variable to a true value, no heuristics get applied to UTF8/16/32, and the result is limited to the suspects plus "ascii". Periodt 💅

💜 Encode::Guess->set_suspects

You can also change the internal suspects list via the "set_suspects" method. Fresh slate energy ✨

use Encode::Guess;
Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);

💖 Encode::Guess->add_suspects

Orrr you can use the "add_suspects" method 🫶 The difference? "set_suspects" flushes the current suspects list while "add_suspects" adds. One is a clean slate, the other is "more is more" 💅

use Encode::Guess;
Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
# now the suspects are euc-jp,shiftjis,7bit-jis, AND
# euc-kr,euc-cn, and big5-eten
Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);

🌈 Encode::decode("Guess" ...)

When you're content with your suspects list — like, genuinely at peace — you can now do this:

my $utf8 = Encode::decode("Guess", $data);

🍓 Encode::Guess->guess($data)

But heads up, it will croak 😤 if:

• Two or more suspects remain
• No suspects left

So instead, bestie, try this:

my $decoder = Encode::Guess->guess($data);

On success, $decoder is an object that's documented in Encode::Encoding — so you can now do this:

my $utf8 = $decoder->decode($data);

On failure, $decoder contains an error message, so the whole thing would look like this:

my $decoder = Encode::Guess->guess($data);
die $decoder unless ref($decoder);
my $utf8 = $decoder->decode($data);

⭐ guess_encoding($data, [, list of suspects])

You can also try the "guess_encoding" function, which is exported by default 🎁 It takes $data to check, and it also takes the list of suspects by option. And plot twist: that optional suspect list is not reflected to the internal suspects list. It's a one-night stand, not a relationship 💀

my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
die $decoder unless ref($decoder);
my $utf8 = $decoder->decode($data);
# check only ascii, utf8 and UTF-(16|32) with BOM
my $decoder = guess_encoding($data);

---

💀 CAVEATS 💀

Buckle up, bestie, this is the serious part. Still cute tho 🎀

• Because of the algorithm used, ISO-8859 series and other single-byte encodings do not work well unless either one of ISO-8859 is the only one suspect (besides ascii and utf8).

use Encode::Guess;
# perhaps ok
my $decoder = guess_encoding($data, 'latin1');
# definitely NOT ok
my $decoder = guess_encoding($data, qw/latin1 greek/);

The reason? Encode::Guess guesses encoding by trial and error. It first splits $data into lines and tries to decode the line for each suspect. It keeps going until all but one encoding is eliminated out of the suspects list. ISO-8859 series is just too successful for most cases (because it fills almost all code points in \x00-\xff). Overachiever behavior, honestly 😭

• Do not mix national standard encodings and the corresponding vendor encodings.

# a very bad idea
my $decoder
   = guess_encoding($data, qw/shiftjis MacJapanese cp932/);

The reason is that vendor encoding is usually a superset of national standard, so it becomes too ambiguous for most cases. Chaos. Not the fun kind 🙈

• On the other hand, mixing various national standard encodings automagically works ✨ unless $data is too short to allow for guessing.

# This is ok if $data is long enough
my $decoder =
 guess_encoding($data, qw/euc-cn
                          euc-jp shiftjis 7bit-jis
                          euc-kr
                          big5-eten/);

• DO NOT PUT TOO MANY SUSPECTS! Don't you dare try something like this! 🔥

my $decoder = guess_encoding($data,
                             Encode->encodings(":all"));

It is, after all, just a guess. You should always be explicit when it comes to encodings. But there are some environments, especially Japanese ones, where guess-coding is a must. Use this module with care 🫶

---

🌸 TO DO 🌸

Encode::Guess does not work on EBCDIC platforms. That's it, that's the todo list 📝 (manifesting a fix one day ✨)

---

👑 SEE ALSO 👑

• Encode
• Encode::Encoding

---

And that's the whole page, bestie! 💖 This lil masterpiece is from perl v5.42.3, dated 2026-11-03 — so yeah, she's fresh ✨ Go forth and guess those encodings responsibly 🧚‍♀️🎀