```{index} single: native_find_encoding; Encode function ``` ```{index} single: Encode::native_find_encoding; Perl function ``` # native_find_encoding Look up an encoding by name and return an object you can call methods on. ## Synopsis ```perl 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: ```perl my $enc = find_encoding('UTF-8'); while (my $line = <$fh>) { my $string = $enc->decode($line); # ... work with $string ... } ``` Query by alias: ```perl 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`. ## See also - `resolve_alias` — get just the canonical name string. - `encodings` — list every name the registry knows. - `encode`, `decode` — the function forms, if you don't want to hold an object.