GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TEXT::ICONV (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



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



DESCRIPTION

The <B>Text::IconvB> 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 <B>-lB> option that lists all supported codesets.

    Utility methods

<B>Text::IconvB> 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 <B>undefB>.

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 <B>eval {}B>, 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 <B>eval {}B>, 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 <B>raise_errorB> 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 <B>raise_errorB> is set to a true value, an exception is raised; otherwise, the convert() method only returns <B>undefB>. By default <B>raise_errorB> 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 <B>raise_errorB> and a corresponding method for setting and getting its value. If <B>raise_errorB> is <B>undefB>, the class-wide settings apply. If <B>raise_errorB> 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 <B>undefB>, e.g.,



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



always returns <B>undefB>. 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(1), iconv(3)
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 ICONV (3) 2007-10-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.