# phpman > perldoc > Text::Iconv

## NAME
    [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown) - Perl interface to iconv() codeset conversion function

## SYNOPSIS
      use [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown);
      $converter = [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)->new("fromcode", "tocode");
      $converted = $converter->convert("Text to convert");

## DESCRIPTION
    The [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown) 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)](https://www.chedong.com/phpMan.php/man/iconv/1/markdown)
    utility should also provide a -l option that lists all supported codesets.

### Utility methods
    [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown) objects also provide the following methods:

### retval
    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

### get_attr
    The get_attr() method allows you to query various attributes which influence the behavior of
### convert
    *discard_ilseq*, e.g.:

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

    See [iconvctl(3)](https://www.chedong.com/phpMan.php/man/iconvctl/3/markdown) 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
    The set_attr() method allows you to set various attributes which influence the behavior of
### convert

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

    See [iconvctl(3)](https://www.chedong.com/phpMan.php/man/iconvctl/3/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)* 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

      [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)->[raise_error(1)](https://www.chedong.com/phpMan.php/man/raiseerror/1/markdown);     # Conversion errors raise exceptions
      [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)->[raise_error(0)](https://www.chedong.com/phpMan.php/man/raiseerror/0/markdown);     # Conversion errors return undef
      $a = [Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)->raise_error(); # Get current setting

### Per-object handling of conversion errors
    As an experimental feature, *[Text::Iconv](https://www.chedong.com/phpMan.php/perldoc/Text%3A%3AIconv/markdown)* 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)](https://www.chedong.com/phpMan.php/man/iconv/3/markdown) 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@dynalabs.de>>

## SEE ALSO
### iconv