POD2::J...:Charset(3)

📦

version 1.013.1 · 10 versions

1.013.1 · opensuse-leap 16.0 (latest)
1.012.2 · centos-stream 9
1.013.1 · centos-stream 10
1.013.1 · alpine 3.24
1.013.1 · arch rolling
1.013.1 · fedora 43
1.012.2 · ubuntu jammy
1.013.1 · fedora 44
1.013.1 · ubuntu noble, ubuntu resolute, ubuntu stonking
1.013.1 · debian bookworm, debian trixie

okay bestie, this is POD2::J...:Charset(3) — the MIME::Charset~[ja] page from the User Contributed Perl Documentation. 💖 It’s all about charset info for MIME messages, and lowkey it’s a lot, but we’re gonna slay it together. ✨

🎀 NAME 🎀

MIME::Charset~[ja] - MIME のためのキャラクタセット情報

So yeah: this module is your go-to for MIME charset information. Periodt. 💅

✨ SYNOPSIS ✨

First, load it up:

use MIME::Charset:

$charset = MIME::Charset->new("euc-jp");

Getting charset info is giving main character energy:

$benc = $charset->body_encoding; # 例 "Q"
$cset = $charset->as_string; # 例 "US-ASCII"
$henc = $charset->header_encoding; # 例 "S"
$cset = $charset->output_charset; # 例 "ISO-2022-JP"

Now the text data conversion part — obsessed:

($text, $charset, $encoding) =
    $charset->header_encode(
       "\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
       "\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
       Charset => 'euc-jp');
# ...例えば (<変換ずみ文字列>, "ISO-2022-JP", "B") を返す。

($text, $charset, $encoding) =
    $charset->body_encode(
        "Collectioneur path\xe9tiquement ",
        Charset => 'latin1');
# ...例えば (<元の文字列>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。

$len = $charset->encoded_header_len(
    "Perl\xe8\xa8\x80\xe8\xaa\x9e",
    Charset => "utf-8",
    Encoding => "b");
# ...例えば 28 を返す。

Module defaults? Yes bestie, you can fiddle with those:

MIME::Charset::alias("csEUCKR", "euc-kr");
MIME::Charset::default("iso-8859-1");
MIME::Charset::fallback("us-ascii");

💀 非OO関数 (近い将来に廃止) 💀 — non-OO functions, deprecated in the near future:

use MIME::Charset qw(:info);

$benc = body_encoding("iso-8859-2"); # "Q"
$cset = canonical_charset("ANSI X3.4-1968"); # "US-ASCII"
$henc = header_encoding("utf-8"); # "S"
$cset = output_charset("shift_jis"); # "ISO-2022-JP"

use MIME::Charset qw(:trans);

($text, $charset, $encoding) =
    header_encode(
       "\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
       "\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
       "euc-jp");
# ...(<変換されたテキスト>, "ISO-2022-JP", "B") を返す。

($text, $charset, $encoding) =
    body_encode(
        "Collectioneur path\xe9tiquement ".
        "\xe9clectique de d\xe9chets",
        "latin1");
# ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。

$len = encoded_header_len(
    "Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28

💖 DESCRIPTION 💖

MIME::Charset provides character set information for MIME messages on the internet. 🌈

🦋 定義 🦋

A キャラクタセット is the MIME character set'' — the method that turns a sequence of octets into a sequence of characters. It includes both the ISO/IEC concepts of 符号化文字集合'' (CCS) and ``文字符号化法'' (CES). 🧚

An エンコーディング is the MIME one — how you represent a message body or message header body as a sequence of printable US-ASCII characters. 💜

🌸 コンストラクタ 🌸

$charset = MIME::Charset->new([CHARSET [, OPTS]]) — creates and returns a charset object. ✨

OPTS can take the following pairs. NOTE: when Unicode/multibyte support is not enabled (see "USE_ENCODE"), no conversion happens, so the following option has no effect.

Mapping => MAPTYPE — whether to extend the actual mapping used for the charset name. "EXTENDED" uses the extended mapping. "STANDARD" uses the standardized strict mapping. Default is "EXTENDED". No cap.

🎀 キャラクタセット情報の取得 🎀

$charset->body_encoding / body_encoding CHARSET — gets the recommended transfer encoding for CHARSET in a message body.

The return value is one of "B" (BASE64), "Q" (QUOTED-PRINTABLE), "S" (whichever is shorter), or "undef" (no transfer encoding needed — 7BIT or 8BIT). This may differ from the message header encoding. 💅

$charset->as_string / canonical_charset CHARSET — gets the canonical name of the charset. Iconic.
$charset->decoder — returns the Encode::Encoding object used to decode the charset into Unicode. If the charset was not specified or is unknown to this module, it returns an undef value. 🫶
$charset->dup — copies the charset object. Simple as that.
$charset->encoder([CHARSET]) — returns the Encode::Encoding object used to encode with the compatible charset recommended for MIME messages on the internet.

If you pass the CHARSET argument, it replaces the $charset object’s encoder (and output charset name) with the one for CHARSET. So the $charset object becomes a converter from the original charset to the new CHARSET. Lowkey powerful. 🔥

$charset->header_encoding / header_encoding CHARSET — gets the recommended encoding method for CHARSET in a message header.

The return value is one of "B", "Q", "S" (whichever is shorter), or "undef" (no encoding needed). This may differ from the message body encoding. 💖

$charset->output_charset / output_charset CHARSET — gets the name of a charset compatible with the specified CHARSET and recommended for MIME messages on the internet (if this module knows it). 🌟

When Unicode/multibyte support is not enabled (see "USE_ENCODE"), this function simply returns the result of "canonical_charset".

🦋 テキストデータの変換 🦋

$charset->body_encode(STRING [, OPTS]) / body_encode STRING, CHARSET [, OPTS] — gets STRING (converted if needed) plus the recommended transfer encoding for a message body. CHARSET is the charset that encodes STRING.

OPTS can take the following pairs. NOTE: when Unicode/multibyte support is not enabled (see "USE_ENCODE"), no conversion happens, so the following options have no effect.

Detect7bit => YESNO — when CHARSET is missing, tries to auto-detect a 7-bit charset. Default is "YES".
Replacement => REPLACEMENT — specifies the error handling method. See "エラー処理".

It returns a 3-element list: (converted string, output charset, transfer encoding). The transfer encoding is one of "BASE64", "QUOTED-PRINTABLE", "7BIT", "8BIT". When the output charset cannot be determined and the converted string contains bytes other than ASCII, the output charset is "undef" and the transfer encoding is "BASE64". The output charset is "US-ASCII" only when the string contains no bytes other than ASCII. 😭✨

$charset->decode(STRING [,CHECK]) — decodes STRING into a Unicode string.

NOTE: when Unicode/multibyte support is not enabled (see "USE_ENCODE"), running this feature dies. 💀

detect_7bit_charset STRING — guesses the 7-bit charset that encodes the string STRING. If STRING contains 8-bit bytes, it returns "undef". Otherwise, if the charset is unknown, it returns the initial charset. 🦋
$charset->encode(STRING [, CHECK]) — encodes STRING (a Unicode string or an ordinary string) using the charset compatible with the original charset and recommended for MIME messages on the internet (if this module knows it). Note that even if the original charset and the compatible charset are the same, the string is decoded to Unicode and then encoded.

NOTE: when Unicode/multibyte support is not enabled (see "USE_ENCODE"), running this feature dies. 🙈

$charset->encoded_header_len(STRING [, ENCODING]) / encoded_header_len STRING, ENCODING, CHARSET — gets the length of STRING when encoded as a message header (assuming no line folding).

ENCODING is one of "B", "Q", "S" (whichever is shorter among "B" and "Q"). 💅

$charset->header_encode(STRING [, OPTS]) / header_encode STRING, CHARSET [, OPTS] — gets STRING (converted if needed) plus the recommended encoding method for a message header. CHARSET is the charset that encodes STRING.

OPTS can take the following pairs. NOTE: when Unicode/multibyte support is not enabled (see "USE_ENCODE"), no conversion happens, so the following options have no effect.

Detect7bit => YESNO — when CHARSET is missing, tries to auto-detect a 7-bit charset. Default is "YES".
Replacement => REPLACEMENT — specifies the error handling method. See "エラー処理".

It returns a 3-element list: (converted string, output charset, encoding method). The encoding method is one of "B", "Q", "undef" (no encoding needed). When the output charset cannot be determined and the converted string contains bytes other than ASCII, the output charset is "8BIT" (this is not a charset name; it is a special value representing data that cannot be encoded) and the encoding method is "undef" (it should not be encoded). The output charset is "US-ASCII" only when the string contains no bytes other than ASCII. 👑💖

$charset->undecode(STRING [,CHECK]) — okay so this one takes a Unicode string STRING and converts it into a string using $charset's input character set. It's equivalent to $charset->decoder->encode(). NOTE: if Unicode/multibyte support is not enabled (see USE_ENCODE), running this feature will die. 😭

🎀 モジュール既定値の操作 (Module Defaults) 🎀

alias ALIAS [, CHARSET] — get/set a charset alias that canonical_charset uses to determine the canonical name. When CHARSET is present and not false, ALIAS is registered as an alias of CHARSET. Otherwise, the alias doesn't change. In either case, it returns the charset that ALIAS is currently registered to. ✨
default [CHARSET] — get/set the default charset. The default charset is what this module uses when the charset for processing is unknown. Modules that use this module are recommended to use this charset when the charset for processing is unknown or when an implicit default is needed. It defaults to US-ASCII. If CHARSET is present and not false, it sets that as the default charset. Otherwise, the default charset doesn't change. In either case, it returns the current default charset. NOTE: you should not change the default charset. 🙈
fallback [CHARSET] — get/set the fallback charset. The fallback charset is what this module uses when conversion with the specified charset fails and the error handling method specifies FALLBACK. Modules that use this module may use this charset as a last resort when charset conversion fails. It defaults to UTF-8. If CHARSET is present and not false, it sets that as the fallback charset. If CHARSET is NONE, it unsets the fallback charset. Otherwise, the fallback charset doesn't change. In either case, it returns the current fallback charset. NOTE: it's worth setting the fallback charset to US-ASCII. The conversion result stays readable even when there is no charset information. 💖
recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]] — get/set a charset's characteristics. If there are optional arguments and any of them is not false, it sets CHARSET's characteristics with those arguments. Otherwise, the characteristics don't change. In either case, it returns the current characteristics of CHARSET as a 3-element list (HEADERENC, BODYENC, ENCCHARSET).
- HEADERENC is the recommended encoding method for message headers. You can specify B, Q, S (whichever is shorter), or undef (no need to encode).
- BODYENC is the recommended transfer encoding for the message body. You can specify B, Q, S (whichever is shorter), or undef (no need to transfer-encode).
- ENCCHARSET is a charset name compatible with the specified CHARSET and recommended for use in MIME messages on the Internet. When conversion is not needed (or this module doesn't know a suitable charset), ENCCHARSET is undef.
- NOTE: future versions of this function may accept other optional arguments (for example, attributes about character width or line folding behavior). Because of that, the return value format may also change. To get individual characteristics, use header_encoding, body_encoding, and output_charset. 🦋

🌟 定数 (Constants) 🌟

USE_ENCODE — the Unicode/multibyte support flag. When Unicode and multibyte support is enabled, a non-empty string is set. Currently this flag is non-empty on Perl 5.7.3 and later, and is an empty string on earlier Perl. ⭐

💅 エラー処理 (Error Handling) 💅

The Replacement option of body_encode and header_encode can take these:

DEFAULT — replace invalid characters with the replacement character. Charsets with a UCM-based encoder may use <subchar>.
FALLBACK — try the DEFAULT method using the fallback charset (see fallback). If the fallback charset is unset and conversion causes an error, the code prints an error message and dies.
CROAK — the code prints an error message and dies immediately. So if you really don't want to die on an error, you must catch the fatal error with eval{}. Same for STRICT.
PERLQQ, HTMLCREF, XMLCREF — use the FB_PERLQQ, FB_HTMLCREF, and FB_XMLCREF methods defined in the Encode module.
数値 (numeric) — you can also specify a number. See "Handling Malformed Data" in Encode for details.

When no error handling method is specified, or a method other than the above is specified, treat it as DEFAULT.

🍓 設定ファイル (Config File) 🍓

The built-in defaults for optional parameters can be changed in the config file MIME/Charset/Defaults.pm. Read MIME/Charset/Defaults.pm.sample for details. 🍓

🌈 VERSION 🌈

See the $VERSION variable.

The development version of this module is at <http://hatuka.nezumi.nu/repos/MIME-Charset/>.

🌸 非互換な変更 (Incompatible Changes) 🌸

1.001

The new() method now returns an object even when the CHARSET argument is not specified.

1.005

The character types included in encoded-word are now as per RFC 2047 section 5 (3). The return value of the encoded_header_len() method also changes.

1.008.2

The body_encoding() method can now return S too.
For UTF-8, the encoding element of the return value of the body_encode() method was fixed to BASE64 in previous releases, but it may become QUOTED-PRINTABLE.

🔥 SEE ALSO 🔥

Multipurpose Internet Mail Extensions (MIME).

🦋 AUTHOR 🦋

Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>

👑 COPYRIGHT 👑

💖 And that's the whole thing, bestie — this is POD2::J...:Charset(3) from perl v5.42.0, dated 2022-08-13. Slay! 🎀

📦 where this page comes from

opensuse-leap 16.0: perl-MIME-Charset 1.013.1-160000.2.2 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms