reference/mbstring/functions/mb-convert-encoding.xml
2c17cef6e71c3d85011319cde128cc4edf89a053
2c17cef6e71c3d85011319cde128cc4edf89a053
...
...
@@ -3,21 +3,22 @@
3
3
<refentry xml:id="function.mb-convert-encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>mb_convert_encoding</refname>
6
-
<refpurpose>Convert 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>mb_convert_encoding</methodname>
13
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
12
+
<type class="union"><type>array</type><type>string</type><type>false</type></type><methodname>mb_convert_encoding</methodname>
13
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>string</parameter></methodparam>
14
14
<methodparam><type>string</type><parameter>to_encoding</parameter></methodparam>
15
-
<methodparam choice="opt"><type>mixed</type><parameter>from_encoding</parameter><initializer>mb_internal_encoding()</initializer></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>array</type><type>string</type><type>null</type></type><parameter>from_encoding</parameter><initializer>&null;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
Converts the character encoding of <type>string</type> <parameter>str</parameter>
19
-
to <parameter>to_encoding</parameter>
20
-
from optionally <parameter>from_encoding</parameter>.
18
+
Converts <parameter>string</parameter> from <parameter>from_encoding</parameter>,
19
+
or the current internal encoding, to <parameter>to_encoding</parameter>.
20
+
If <parameter>string</parameter> is an &array;, all its &string; values will be
21
+
converted recursively.
21
22
</para>
22
23
</refsect1>
23
24
...
...
@@ -26,10 +27,10 @@
26
27
<para>
27
28
<variablelist>
28
29
<varlistentry>
29
-
<term><parameter>str</parameter></term>
30
+
<term><parameter>string</parameter></term>
30
31
<listitem>
31
32
<para>
32
-
The <type>string</type> being encoded.
33
+
The &string; or &array; to be converted.
33
34
</para>
34
35
</listitem>
35
36
</varlistentry>
...
...
@@ -37,7 +38,7 @@
37
38
<term><parameter>to_encoding</parameter></term>
38
39
<listitem>
39
40
<para>
40
-
The type of encoding that <parameter>str</parameter> is being converted to.
41
+
The desired encoding of the result.
41
42
</para>
42
43
</listitem>
43
44
</varlistentry>
...
...
@@ -45,15 +46,20 @@
45
46
<term><parameter>from_encoding</parameter></term>
46
47
<listitem>
47
48
<para>
48
-
Is specified by character code names before conversion. It is either
49
-
an <type>array</type>, or a comma separated enumerated list.
50
-
If <parameter>from_encoding</parameter> is not specified, the internal
51
-
encoding will be used.
52
-
<!-- link to internal encoding info -->
49
+
The current encoding used to interpret <parameter>string</parameter>.
50
+
Multiple encodings may be specified as an &array; or comma separated
51
+
list, in which case the correct encoding will be guessed using the
52
+
same algorithm as <function>mb_detect_encoding</function>.
53
53
</para>
54
54
<para>
55
-
See <link linkend="mbstring.supported-encodings">supported
56
-
encodings</link>.
55
+
If <parameter>from_encoding</parameter> is omitted or &null;, the
56
+
<link linkend="ini.mbstring.internal-encoding">mbstring.internal_encoding setting</link>
57
+
will be used if set, otherwise the <link linkend="ini.default-charset">default_charset setting</link>.
58
+
</para>
59
+
<para>
60
+
See <link linkend="mbstring.supported-encodings">supported encodings</link>
61
+
for valid values of <parameter>to_encoding</parameter>
62
+
and <parameter>from_encoding</parameter>.
57
63
</para>
58
64
</listitem>
59
65
</varlistentry>
...
...
@@ -64,10 +70,75 @@
64
70
<refsect1 role="returnvalues">
65
71
&reftitle.returnvalues;
66
72
<para>
67
-
The encoded <type>string</type>.
73
+
The encoded &string; or &array; on success, &return.falseforfailure;.
68
74
</para>
69
75
</refsect1>
70
76
77
+
<refsect1 role="errors">
78
+
&reftitle.errors;
79
+
<para>
80
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the
81
+
value of <parameter>to_encoding</parameter> or
82
+
<parameter>from_encoding</parameter> is an invalid encoding.
83
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
84
+
</para>
85
+
</refsect1>
86
+
87
+
<refsect1 role="changelog">
88
+
&reftitle.changelog;
89
+
<informaltable>
90
+
<tgroup cols="2">
91
+
<thead>
92
+
<row>
93
+
<entry>&Version;</entry>
94
+
<entry>&Description;</entry>
95
+
</row>
96
+
</thead>
97
+
<tbody>
98
+
<row>
99
+
<entry>8.2.0</entry>
100
+
<entry>
101
+
<function>mb_convert_encoding</function> will no longer return
102
+
the following non text encodings:
103
+
<literal>"Base64"</literal>, <literal>"QPrint"</literal>,
104
+
<literal>"UUencode"</literal>, <literal>"HTML entities"</literal>,
105
+
<literal>"7 bit"</literal> and <literal>"8 bit"</literal>.
106
+
</entry>
107
+
</row>
108
+
<row>
109
+
<entry>8.0.0</entry>
110
+
<entry>
111
+
<function>mb_convert_encoding</function> will now throw a
112
+
<classname>ValueError</classname> when
113
+
<parameter>to_encoding</parameter> is passed an invalid encoding.
114
+
</entry>
115
+
</row>
116
+
<row>
117
+
<entry>8.0.0</entry>
118
+
<entry>
119
+
<function>mb_convert_encoding</function> will now throw a
120
+
<classname>ValueError</classname> when
121
+
<parameter>from_encoding</parameter> is passed an invalid encoding.
122
+
</entry>
123
+
</row>
124
+
<row>
125
+
<entry>8.0.0</entry>
126
+
<entry>
127
+
<parameter>from_encoding</parameter> is nullable now.
128
+
</entry>
129
+
</row>
130
+
<row>
131
+
<entry>7.2.0</entry>
132
+
<entry>
133
+
This function now also accepts an &array; as <parameter>string</parameter>.
134
+
Formerly, only &string;s have been supported.
135
+
</entry>
136
+
</row>
137
+
</tbody>
138
+
</tgroup>
139
+
</informaltable>
140
+
</refsect1>
141
+
71
142
<refsect1 role="examples">
72
143
&reftitle.examples;
73
144
<para>
...
...
@@ -85,7 +156,7 @@ $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");
85
156
/* Auto detect encoding from JIS, eucjp-win, sjis-win, then convert str to UCS-2LE */
86
157
$str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");
87
158
88
-
/* "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
159
+
/* If mbstring.language is "Japanese", "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
89
160
$str = mb_convert_encoding($str, "EUC-JP", "auto");
90
161
?>
91
162
]]>
...
...
@@ -99,12 +170,13 @@ $str = mb_convert_encoding($str, "EUC-JP", "auto");
99
170
<para>
100
171
<simplelist>
101
172
<member><function>mb_detect_order</function></member>
173
+
<member><methodname>UConverter::transcode</methodname></member>
174
+
<member><function>iconv</function></member>
102
175
</simplelist>
103
176
</para>
104
177
</refsect1>
105
178
106
179
</refentry>
107
-
108
180
<!-- Keep this comment at the end of the file
109
181
Local variables:
110
182
mode: sgml
111
183