<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.mb-convert-encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>mb_convert_encoding</refname>

<refpurpose>ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>string</type><type>false</type></type><methodname>mb_convert_encoding</methodname>

<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>string</parameter></methodparam>

<methodparam><type>string</type><parameter>to_encoding</parameter></methodparam>

<methodparam choice="opt"><type class="union"><type>array</type><type>string</type><type>null</type></type><parameter>from_encoding</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<para>

文字列 <parameter>string</parameter> の文字エンコーディングを、

<parameter>from_encoding</parameter> または現在の内部エンコーディングから

<parameter>to_encoding</parameter> に変換します。

<parameter>string</parameter> が配列の場合、それに含まれる全ての文字列型の値が再帰的に変換されます。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

変換する &string; または &array;

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>to_encoding</parameter></term>

<listitem>

<para>

変換したい文字エンコーディング。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>from_encoding</parameter></term>

<listitem>

<para>

<parameter>string</parameter> を解釈するのに使われている

現在の文字エンコーディング。

配列またはカンマ区切りの文字列とすることで、

複数のエンコーディングを指定できます。

この場合、正しいエンコーディングを

<function>mb_detect_encoding</function>

と同じアルゴリズムで推測します。

</para>

<para>

<parameter>from_encoding</parameter> が省略されたり、

&null; だった場合は、

<link linkend="ini.mbstring.internal-encoding">mbstring.internal_encoding setting</link> が設定されていた場合、それを使います。

設定されていない場合は、

<link linkend="ini.default-charset">default_charset setting</link>

を使います。

</para>

<para>

<parameter>to_encoding</parameter>

や <parameter>from_encoding</parameter>

に指定できる値は、

<link linkend="mbstring.supported-encodings">

サポートされる文字エンコーディング</link>を参照ください。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

成功時に、変換後の文字列または配列を返します。

&return.falseforfailure;

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

PHP 8.0.0 以降では、

<parameter>to_encoding</parameter> または

<parameter>from_encoding</parameter> に不正なエンコーディングが渡された場合、

<classname>ValueError</classname> がスローされるようになりました。

これより前のバージョンでは、

<constant>E_WARNING</constant> が発生していました。

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.2.0</entry>

<entry>

<function>mb_convert_encoding</function> は、

以下のテキストでないエンコーディングを返さなくなりました:

<literal>"Base64"</literal>, <literal>"QPrint"</literal>,

<literal>"UUencode"</literal>, <literal>"HTML entities"</literal>,

<literal>"7 bit"</literal>, <literal>"8 bit"</literal>

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>to_encoding</parameter> に不正なエンコーディングが渡された場合、

<classname>ValueError</classname> がスローされるようになりました。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>from_encoding</parameter> に不正なエンコーディングが渡された場合、

<classname>ValueError</classname> がスローされるようになりました。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>from_encoding</parameter> は、nullable になりました。

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

この関数は、 <parameter>string</parameter> に

配列を受け入れるようになりました。

これより前のバージョンでは、文字列のみがサポートされていました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>mb_convert_encoding</function> の例</title>

<programlisting role="php" annotations="non-interactive">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>mb_detect_order</function></member>

<member><methodname>UConverter::transcode</methodname></member>

<member><function>iconv</function></member>

</simplelist>

</para>

</refsect1>

</refentry>