reference/iconv/functions/iconv.xml
a223531900823441f82d178ca4e94c0444f24576
a223531900823441f82d178ca4e94c0444f24576
...
...
@@ -3,21 +3,20 @@
3
3
<refentry xml:id="function.iconv" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>iconv</refname>
6
-
<refpurpose>Convert string to requested character encoding</refpurpose>
6
+
<refpurpose>Convert a string from one character encoding to another</refpurpose>
7
7
</refnamediv>
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>iconv</methodname>
13
-
<methodparam><type>string</type><parameter>in_charset</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>out_charset</parameter></methodparam>
15
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>iconv</methodname>
13
+
<methodparam><type>string</type><parameter>from_encoding</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>to_encoding</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
Performs a character set conversion on the string
19
-
<parameter>str</parameter> from <parameter>in_charset</parameter>
20
-
to <parameter>out_charset</parameter>.
18
+
Converts <parameter>string</parameter> from <parameter>from_encoding</parameter>
19
+
to <parameter>to_encoding</parameter>.
21
20
</para>
22
21
</refsect1>
23
22
...
...
@@ -26,36 +25,45 @@
26
25
<para>
27
26
<variablelist>
28
27
<varlistentry>
29
-
<term><parameter>in_charset</parameter></term>
28
+
<term><parameter>from_encoding</parameter></term>
30
29
<listitem>
31
30
<para>
32
-
The input charset.
31
+
The current encoding used to interpret <parameter>string</parameter>.
33
32
</para>
34
33
</listitem>
35
34
</varlistentry>
36
35
<varlistentry>
37
-
<term><parameter>out_charset</parameter></term>
36
+
<term><parameter>to_encoding</parameter></term>
38
37
<listitem>
39
38
<para>
40
-
The output charset.
39
+
The desired encoding of the result.
41
40
</para>
42
41
<para>
43
-
If you append the string <literal>//TRANSLIT</literal> to
44
-
<parameter>out_charset</parameter> transliteration is activated. This
42
+
If the string <literal>//TRANSLIT</literal> is appended to
43
+
<parameter>to_encoding</parameter>, then transliteration is activated. This
45
44
means that when a character can't be represented in the target charset,
46
-
it can be approximated through one or several similarly looking
47
-
characters. If you append the string <literal>//IGNORE</literal>,
45
+
it may be approximated through one or several similarly looking
46
+
characters. If the string <literal>//IGNORE</literal> is appended,
48
47
characters that cannot be represented in the target charset are silently
49
48
discarded. Otherwise, <constant>E_NOTICE</constant> is generated and the function
50
-
will return &false;.
49
+
will return &false;.
51
50
</para>
51
+
<caution>
52
+
<para>
53
+
If and how <literal>//TRANSLIT</literal> works exactly depends on the
54
+
system's iconv() implementation (cf. <constant>ICONV_IMPL</constant>).
55
+
Some implementations are known to ignore <literal>//TRANSLIT</literal>,
56
+
so the conversion is likely to fail for characters which are illegal for
57
+
the <parameter>to_encoding</parameter>.
58
+
</para>
59
+
</caution>
52
60
</listitem>
53
61
</varlistentry>
54
62
<varlistentry>
55
-
<term><parameter>str</parameter></term>
63
+
<term><parameter>string</parameter></term>
56
64
<listitem>
57
65
<para>
58
-
The string to be converted.
66
+
The &string; to be converted.
59
67
</para>
60
68
</listitem>
61
69
</varlistentry>
...
...
@@ -66,36 +74,10 @@
66
74
<refsect1 role="returnvalues">
67
75
&reftitle.returnvalues;
68
76
<para>
69
-
Returns the converted string&return.falseforfailure;.
77
+
Returns the converted string,&return.falseforfailure;.
70
78
</para>
71
79
</refsect1>
72
80
73
-
<refsect1 role="changelog">
74
-
&reftitle.changelog;
75
-
<para>
76
-
<informaltable>
77
-
<tgroup cols="2">
78
-
<thead>
79
-
<row>
80
-
<entry>&Version;</entry>
81
-
<entry>&Description;</entry>
82
-
</row>
83
-
</thead>
84
-
<tbody>
85
-
<row>
86
-
<entry>5.4.0</entry>
87
-
<entry>
88
-
Since this version, the function returns &false; on illegal characters,
89
-
unless <literal>//IGNORE</literal> is specified in output charset.
90
-
Before, it returned partial output string.
91
-
</entry>
92
-
</row>
93
-
</tbody>
94
-
</tgroup>
95
-
</informaltable>
96
-
</para>
97
-
</refsect1>
98
-
99
81
<refsect1 role="examples">
100
82
&reftitle.examples;
101
83
<para>
...
...
@@ -128,10 +110,29 @@ Notice: iconv(): Detected an illegal character in input string in .\iconv-exampl
128
110
</para>
129
111
</refsect1>
130
112
113
+
<refsect1 role="notes">
114
+
&reftitle.notes;
115
+
<note>
116
+
<para>
117
+
The character encodings and options available depend on the installed implementation
118
+
of iconv. If the argument to <parameter>from_encoding</parameter>
119
+
or <parameter>to_encoding</parameter> is not supported on the current system, &false;
120
+
will be returned.
121
+
</para>
122
+
</note>
123
+
</refsect1>
131
124
125
+
<refsect1 role="seealso">
126
+
&reftitle.seealso;
127
+
<para>
128
+
<simplelist>
129
+
<member><function>mb_convert_encoding</function></member>
130
+
<member><methodname>UConverter::transcode</methodname></member>
131
+
</simplelist>
132
+
</para>
133
+
</refsect1>
132
134
133
135
</refentry>
134
-
135
136
<!-- Keep this comment at the end of the file
136
137
Local variables:
137
138
mode: sgml
138
139