phpman > perldoc > Text::Iconv(3pm)

NAME
    Text::Iconv - Perl interface to iconv() codeset conversion function

SYNOPSIS
      use Text::Iconv;
      $converter = Text::Iconv->new("fromcode", "tocode");
      $converted = $converter->convert("Text to convert");

DESCRIPTION
    The Text::Iconv module provides a Perl interface to the iconv() function as defined by the
    Single UNIX Specification.

    The convert() method converts the encoding of characters in the input string from the *fromcode*
    codeset to the *tocode* codeset, and returns the result.

    Settings of *fromcode* and *tocode* and their permitted combinations are
    implementation-dependent. Valid values are specified in the system documentation; the iconv(1)
    utility should also provide a -l option that lists all supported codesets.

  Utility methods
    Text::Iconv objects also provide the following methods:

    retval() returns the return value of the underlying iconv() function for the last conversion;
    according to the Single UNIX Specification, this value indicates "the number of non-identical
    conversions performed." Note, however, that iconv implementations vary widely in the
    interpretation of this specification.

    This method can be called after calling convert(), e.g.:

      $result = $converter->convert("lorem ipsum dolor sit amet");
      $retval = $converter->retval;

    When called before the first call to convert(), or if an error occured during the conversion,
    retval() returns undef.

    get_attr(): This method is only available with GNU libiconv, otherwise it throws an exception.
    The get_attr() method allows you to query various attributes which influence the behavior of
    convert(). The currently supported attributes are *trivialp*, *transliterate*, and
    *discard_ilseq*, e.g.:

      $state = $converter->get_attr("transliterate");

    See iconvctl(3) for details. To ensure portability to other iconv implementations you should
    first check for the availability of this method using eval {}, e.g.:

        eval { $conv->get_attr("trivialp") };
        if ($@)
        {
          # get_attr() is not available
        }
        else
        {
          # get_attr() is available
        }

    This method should be considered experimental.

    set_attr(): This method is only available with GNU libiconv, otherwise it throws an exception.
    The set_attr() method allows you to set various attributes which influence the behavior of
    convert(). The currently supported attributes are *transliterate* and *discard_ilseq*, e.g.:

      $state = $converter->set_attr("transliterate");

    See iconvctl(3) for details. To ensure portability to other iconv implementations you should
    first check for the availability of this method using eval {}, cf. the description of set_attr()
    above.

    This method should be considered experimental.

ERRORS
    If the conversion can't be initialized an exception is raised (using croak()).

  Handling of conversion errors
    *Text::Iconv* provides a class attribute raise_error and a corresponding class method for
    setting and getting its value. The handling of errors during conversion depends on the setting
    of this attribute. If raise_error is set to a true value, an exception is raised; otherwise, the
    convert() method only returns undef. By default raise_error is false. Example usage:

      Text::Iconv->raise_error(1);     # Conversion errors raise exceptions
      Text::Iconv->raise_error(0);     # Conversion errors return undef
      $a = Text::Iconv->raise_error(); # Get current setting

  Per-object handling of conversion errors
    As an experimental feature, *Text::Iconv* also provides an instance attribute raise_error and a
    corresponding method for setting and getting its value. If raise_error is undef, the class-wide
    settings apply. If raise_error is 1 or 0 (true or false), the object settings override the
    class-wide settings.

    Consult iconv(3) for details on errors that might occur.

  Conversion of undef
    Converting undef, e.g.,

      $converted = $converter->convert(undef);

    always returns undef. This is not considered an error.

NOTES
    The supported codesets, their names, the supported conversions, and the quality of the
    conversions are all system-dependent.

AUTHOR
    Michael Piotrowski <mxp AT dynalabs.de>

SEE ALSO
    iconv(1), iconv(3)