native_find_encoding#

Look up an encoding by name and return an object you can call methods on.

Synopsis#

my $enc = find_encoding($name);
my $bytes  = $enc->encode($string);
my $string = $enc->decode($bytes);
my $canon  = $enc->name;

What you get back#

A blessed object. UTF-8 family encodings return an Encode::utf8 object; everything else returns an Encode::XS object. If the name cannot be resolved, find_encoding returns undef.

The object exposes four methods: encode, decode, name (returns the canonical string), and perlio_ok (true for UTF-8 family, false otherwise). renew is also accepted and returns the same object.

Name resolution is case-insensitive and treats - and _ interchangeably. “UTF8”, “utf-8”, and “utf_8” all resolve to the same object.

Examples#

Cache an encoding object and reuse it in a loop:

my $enc = find_encoding('UTF-8');
while (my $line = <$fh>) {
    my $string = $enc->decode($line);
    # ... work with $string ...
}

Query by alias:

my $enc = find_encoding('latin1');
print $enc->name;   # iso-8859-1

Edge cases#

Unknown names return undef after falling back to Encode::Alias::find_alias for dynamically registered aliases (e.g. "locale").
The object is a blessed hashref with a single Name key; code that pokes inside works but is not portable across Encode implementations.

Differences from upstream#

The returned object carries only the Name key rather than the full encoding table upstream Encode::XS stores. The four documented methods behave identically; direct field access does not. Covered by t/81-xs-native/Encode/020-find-encoding.t and t/81-xs-native/Encode/070-encoding-object.t.