1Iconv(3)              User Contributed Perl Documentation             Iconv(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14       The Text::Iconv module provides a Perl interface to the iconv()
15       function as defined by the Single UNIX Specification.
16
17       The convert() method converts the encoding of characters in the input
18       string from the fromcode codeset to the tocode codeset, and returns the
19       result.
20
21       Settings of fromcode and tocode and their permitted combinations are
22       implementation-dependent.  Valid values are specified in the system
23       documentation; the iconv(1) utility should also provide a -l option
24       that lists all supported codesets.
25
26   Utility methods
27       Text::Iconv objects also provide the following methods:
28
29       retval() returns the return value of the underlying iconv() function
30       for the last conversion; according to the Single UNIX Specification,
31       this value indicates "the number of non-identical conversions
32       performed."  Note, however, that iconv implementations vary widely in
33       the interpretation of this specification.
34
35       This method can be called after calling convert(), e.g.:
36
37         $result = $converter->convert("lorem ipsum dolor sit amet");
38         $retval = $converter->retval;
39
40       When called before the first call to convert(), or if an error occured
41       during the conversion, retval() returns undef.
42
43       get_attr(): This method is only available with GNU libiconv, otherwise
44       it throws an exception.  The get_attr() method allows you to query
45       various attributes which influence the behavior of convert().  The
46       currently supported attributes are trivialp, transliterate, and
47       discard_ilseq, e.g.:
48
49         $state = $converter->get_attr("transliterate");
50
51       See iconvctl(3) for details.  To ensure portability to other iconv
52       implementations you should first check for the availability of this
53       method using eval {}, e.g.:
54
55           eval { $conv->get_attr("trivialp") };
56           if ($@)
57           {
58             # get_attr() is not available
59           }
60           else
61           {
62             # get_attr() is available
63           }
64
65       This method should be considered experimental.
66
67       set_attr(): This method is only available with GNU libiconv, otherwise
68       it throws an exception.  The set_attr() method allows you to set
69       various attributes which influence the behavior of convert().  The
70       currently supported attributes are transliterate and discard_ilseq,
71       e.g.:
72
73         $state = $converter->set_attr("transliterate");
74
75       See iconvctl(3) for details.  To ensure portability to other iconv
76       implementations you should first check for the availability of this
77       method using eval {}, cf. the description of set_attr() above.
78
79       This method should be considered experimental.
80

ERRORS

82       If the conversion can't be initialized an exception is raised (using
83       croak()).
84
85   Handling of conversion errors
86       Text::Iconv provides a class attribute raise_error and a corresponding
87       class method for setting and getting its value.  The handling of errors
88       during conversion depends on the setting of this attribute.  If
89       raise_error is set to a true value, an exception is raised; otherwise,
90       the convert() method only returns undef.  By default raise_error is
91       false.  Example usage:
92
93         Text::Iconv->raise_error(1);     # Conversion errors raise exceptions
94         Text::Iconv->raise_error(0);     # Conversion errors return undef
95         $a = Text::Iconv->raise_error(); # Get current setting
96
97   Per-object handling of conversion errors
98       As an experimental feature, Text::Iconv also provides an instance
99       attribute raise_error and a corresponding method for setting and
100       getting its value.  If raise_error is undef, the class-wide settings
101       apply.  If raise_error is 1 or 0 (true or false), the object settings
102       override the class-wide settings.
103
104       Consult iconv(3) for details on errors that might occur.
105
106   Conversion of undef
107       Converting undef, e.g.,
108
109         $converted = $converter->convert(undef);
110
111       always returns undef.  This is not considered an error.
112

NOTES

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

AUTHOR

118       Michael Piotrowski <mxp@dynalabs.de>
119

SEE ALSO

121       iconv(1), iconv(3)
122
123
124
125perl v5.36.0                      2022-07-22                          Iconv(3)
Impressum