=begin pod :kind("Type") :subkind("role") :category("basic")

=TITLE role Encoding

=SUBTITLE Support for character encodings.

    role Encoding { ... }

The C<Encoding> role is implemented by classes that provide a character
encoding, such as ASCII or UTF-8. Besides being used by the built-in character
encodings, it may also be implemented by users to provide new encodings.
Instances of objects doing this role are typically obtained using
L<Encoding::Registry|/type/Encoding::Registry>. For a list of supported encodings, see
L<IO::Handle|/type/IO::Handle#method_encoding>.

All methods provided by this role are stubs; they should be implemented by
consumers of the role.

=head1 Methods

=head2 method name

    method name(--> Str)

Abstract method that would return the primary name of the encoding.

=head2 method alternative-names

    method alternative-names()

Abstract methods that should get a list of alternative names for the encoding.

=head2 method decoder

    method decoder(*%options --> Encoding::Decoder)

Should get a character decoder instance for this encoding, configured with the
provided options. Options vary by encoding. The built-in encodings all
support C<translate-nl>, which if C<True> will translate C<\r\n> into
C<\n> while decoding.

=head2 method encoder

Defined as:

    method encoder(*%options --> Encoding::Encoder)

Gets a character encoder instance for this encoding, configured with the
provided options. Options vary by encoding. The built-in encodings all support
both C<replacement> (either a C<Str> replacement sequence or C<True> to use a
default replacement sequence for unencodable characters) and C<translate-nl>
(when set to C<True>, turns C<\n> into C<\r\n> if the current platform is
Windows).

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
