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@dynalabs.de>
SEE ALSO¶
iconv(1),
iconv(3)