.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Iconv 3pm"
.TH Iconv 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Iconv \- Perl interface to iconv() codeset conversion function
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Text::Iconv;
\&  $converter = Text::Iconv\->new("fromcode", "tocode");
\&  $converted = $converter\->convert("Text to convert");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBText::Iconv\fR module provides a Perl interface to the \fBiconv()\fR
function as defined by the Single \s-1UNIX\s0 Specification.
.PP
The \fBconvert()\fR method converts the encoding of characters in the input
string from the \fIfromcode\fR codeset to the \fItocode\fR codeset, and
returns the result.
.PP
Settings of \fIfromcode\fR and \fItocode\fR and their permitted combinations
are implementation-dependent.  Valid values are specified in the
system documentation; the \fBiconv\fR\|(1) utility should also provide a \fB\-l\fR
option that lists all supported codesets.
.SS "Utility methods"
.IX Subsection "Utility methods"
\&\fBText::Iconv\fR objects also provide the following methods:
.PP
\&\fBretval()\fR returns the return value of the underlying \fBiconv()\fR function
for the last conversion; according to the Single \s-1UNIX\s0 Specification,
this value indicates \*(L"the number of non-identical conversions
performed.\*(R"  Note, however, that iconv implementations vary widely in
the interpretation of this specification.
.PP
This method can be called after calling \fBconvert()\fR, e.g.:
.PP
.Vb 2
\&  $result = $converter\->convert("lorem ipsum dolor sit amet");
\&  $retval = $converter\->retval;
.Ve
.PP
When called before the first call to \fBconvert()\fR, or if an error occured
during the conversion, \fBretval()\fR returns \fBundef\fR.
.PP
\&\fBget_attr()\fR: This method is only available with \s-1GNU\s0 libiconv, otherwise
it throws an exception.  The \fBget_attr()\fR method allows you to query
various attributes which influence the behavior of \fBconvert()\fR.  The
currently supported attributes are \fItrivialp\fR, \fItransliterate\fR, and
\&\fIdiscard_ilseq\fR, e.g.:
.PP
.Vb 1
\&  $state = $converter\->get_attr("transliterate");
.Ve
.PP
See \fBiconvctl\fR\|(3) for details.  To ensure portability to other iconv
implementations you should first check for the availability of this
method using \fBeval {}\fR, e.g.:
.PP
.Vb 9
\&    eval { $conv\->get_attr("trivialp") };
\&    if ($@)
\&    {
\&      # get_attr() is not available
\&    }
\&    else
\&    {
\&      # get_attr() is available
\&    }
.Ve
.PP
This method should be considered experimental.
.PP
\&\fBset_attr()\fR: This method is only available with \s-1GNU\s0 libiconv, otherwise
it throws an exception.  The \fBset_attr()\fR method allows you to set
various attributes which influence the behavior of \fBconvert()\fR.  The
currently supported attributes are \fItransliterate\fR and
\&\fIdiscard_ilseq\fR, e.g.:
.PP
.Vb 1
\&  $state = $converter\->set_attr("transliterate");
.Ve
.PP
See \fBiconvctl\fR\|(3) for details.  To ensure portability to other iconv
implementations you should first check for the availability of this
method using \fBeval {}\fR, cf. the description of \fBset_attr()\fR above.
.PP
This method should be considered experimental.
.SH "ERRORS"
.IX Header "ERRORS"
If the conversion can't be initialized an exception is raised (using
\&\fBcroak()\fR).
.SS "Handling of conversion errors"
.IX Subsection "Handling of conversion errors"
\&\fIText::Iconv\fR provides a class attribute \fBraise_error\fR 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 \fBraise_error\fR is set to a true value, an exception is
raised; otherwise, the \fBconvert()\fR method only returns \fBundef\fR.  By
default \fBraise_error\fR is false.  Example usage:
.PP
.Vb 3
\&  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
.Ve
.SS "Per-object handling of conversion errors"
.IX Subsection "Per-object handling of conversion errors"
As an experimental feature, \fIText::Iconv\fR also provides an instance
attribute \fBraise_error\fR and a corresponding method for setting and
getting its value.  If \fBraise_error\fR is \fBundef\fR, the class-wide
settings apply.  If \fBraise_error\fR is 1 or 0 (true or false), the
object settings override the class-wide settings.
.PP
Consult \fBiconv\fR\|(3) for details on errors that might occur.
.SS "Conversion of \fBundef\fP"
.IX Subsection "Conversion of undef"
Converting \fBundef\fR, e.g.,
.PP
.Vb 1
\&  $converted = $converter\->convert(undef);
.Ve
.PP
always returns \fBundef\fR.  This is not considered an error.
.SH "NOTES"
.IX Header "NOTES"
The supported codesets, their names, the supported conversions, and
the quality of the conversions are all system-dependent.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Piotrowski <mxp@dynalabs.de>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBiconv\fR\|(1), \fBiconv\fR\|(3)