######
Encode
######


****
NAME
****


Kernel::System::Encode - character encodings


***********
DESCRIPTION
***********


This module will use Perl's Encode module (Perl 5.8.0 or higher is required).


****************
PUBLIC INTERFACE
****************


new()
=====


Don't use the constructor directly, use the ObjectManager instead:


.. code-block:: perl

     my $EncodeObject = $Kernel::OM->Get('Kernel::System::Encode');



Convert()
=========


Convert a string from one charset to another charset.


.. code-block:: perl

     my $utf8 = $EncodeObject->Convert(
         Text => $iso_8859_1_string,
         From => 'iso-8859-1',
         To   => 'utf-8',
     );
 
     my $iso_8859_1 = $EncodeObject->Convert(
         Text => $utf-8_string,
         From => 'utf-8',
         To   => 'iso-8859-1',
     );


There is also a Force => 1 option if you need to force the
already converted string. And Check => 1 if the string result
should be checked to be a valid string (e. g. valid utf-8 string).


Convert2CharsetInternal()
=========================


Convert given charset into the internal used charset (utf-8).
Should be used on all I/O interfaces.


.. code-block:: perl

     my $String = $EncodeObject->Convert2CharsetInternal(
         Text => $String,
         From => $SourceCharset,
     );



EncodeInput()
=============


Convert internal used charset (e. g. utf-8) into given charset (utf-8).

Should be used on all I/O interfaces if data is already utf-8 to set the utf-8 stamp.


.. code-block:: perl

     $EncodeObject->EncodeInput( \$String );
 
     $EncodeObject->EncodeInput( \@Array );



EncodeOutput()
==============


Convert utf-8 to a sequence of bytes. All possible characters have
a UTF-8 representation so this function cannot fail.

This should be used in for output of utf-8 chars.


.. code-block:: perl

     $EncodeObject->EncodeOutput( \$String );
 
     $EncodeObject->EncodeOutput( \@Array );



ConfigureOutputFileHandle()
===========================


switch output file handle to utf-8 output.


.. code-block:: perl

     $EncodeObject->ConfigureOutputFileHandle( FileHandle => \*STDOUT );



EncodingIsAsciiSuperset()
=========================


Checks if an encoding is a super-set of ASCII, that is, encodes the
codepoints from 0 to 127 the same way as ASCII.


.. code-block:: perl

     my $IsSuperset = $EncodeObject->EncodingIsAsciiSuperset(
         Encoding    => 'UTF-8',
     );



FindAsciiSupersetEncoding()
===========================


From a list of character encodings, returns the first that
is a super-set of ASCII. If none matches, \ ``ASCII``\  is returned.


.. code-block:: perl

     my $Encoding = $EncodeObject->FindAsciiSupersetEncoding(
         Encodings   => [ 'UTF-16LE', 'UTF-8' ],
     );



RemoveUTF8BOM()
===============


Removes UTF-8 BOM (if present) from start of given string.


.. code-block:: perl

     my $StringWithoutBOM = $EncodeObject->RemoveUTF8BOM(
         String => '<BOM>....',
     );
 
     Returns given string without BOM.