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

<!-- $Revision$ -->

<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b Maintainer: hirokawa Status: ready -->

<!-- CREDITS: shimooka -->

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

<refnamediv>

<refname>strtr</refname>

<refpurpose>文字の変換あるいは部分文字列の置換を行う</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>strtr</methodname>

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

<methodparam><type>string</type><parameter>from</parameter></methodparam>

<methodparam><type>string</type><parameter>to</parameter></methodparam>

</methodsynopsis>

<simpara>代替のシグネチャ (名前付き引数をサポートしていません):</simpara>

<methodsynopsis>

<type>string</type><methodname>strtr</methodname>

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

<methodparam><type>array</type><parameter>replace_pairs</parameter></methodparam>

</methodsynopsis>

<para>

引数を三つ渡した場合、この関数は <parameter>string</parameter>

のコピーを返します。その際に、文字列中に <parameter>from</parameter>

の各文字 (シングルバイト) があれば <parameter>to</parameter>

の対応する文字に変換します。つまり、すべての <literal>$from[$n]</literal>

が <literal>$to[$n]</literal> に置換されることになります。ここで

<literal>$n</literal> は、どちらの引数でも共通に有効なオフセットです。

</para>

<para>

<parameter>from</parameter> と <parameter>to</parameter>

の長さが異なる場合、長い方の余分な文字は無視されます。

返される文字列の長さは、もとの <parameter>string</parameter> と同じになります。

</para>

<para>

引数を二つだけ渡す場合は、二番目の引数を

<literal>array('from' =&gt; 'to', ...)</literal> 形式の配列にしなければなりません。

返される値は文字列で、もとの文字列中にある配列のキーと同じ部分を対応する値で置換したものとなります。

一番長いキーから順に調べます。一度部分文字列の置換を行うと、

置換後の文字列がさらに置換の対象となることはありません。

</para>

<para>

この場合は、配列のキーと値は任意の長さにすることができますが、キーを空にすることだけはできません。

さらに、返される文字列の長さはもとの <parameter>string</parameter>

とは異なる可能性があります。

しかし、この関数が最も効率的に働くのは、すべてのキーが同じ長さである場合です。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

変換する文字列。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>from</parameter></term>

<listitem>

<para>

<parameter>to</parameter> に変換される文字列。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>to</parameter></term>

<listitem>

<para>

<parameter>from</parameter> を置換する文字列。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>replace_pairs</parameter></term>

<listitem>

<para>

<parameter>replace_pairs</parameter> パラメータを

<parameter>to</parameter> や <parameter>from</parameter>

のかわりに使用することができます。この場合は

<literal>array('from' =&gt; 'to', ...)</literal> 形式の配列となります。

</para>

<para>

<parameter>replace_pairs</parameter> の中に空文字列

(<literal>""</literal>) のキーがある場合は、その要素は無視されます。

PHP 8.0.0 以降では、この場合 <constant>E_WARNING</constant> が発生します。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

変換後の文字列を返します。

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>strtr</function> の例</title>

<programlisting role="php">

<![CDATA[

<?php

$addr = "The river å";

// この形式の場合、strtr() はバイト単位での変換を行います。

// したがって、ここではシングルバイトエンコーディングを想定しています。

$addr = strtr($addr, "äåö", "aao");

echo $addr, PHP_EOL;

?>

]]>

</programlisting>

</example>

</para>

<para>

次の例は、引数を二つだけ指定して <function>strtr</function>

をコールしたときの挙動を示すものです。置換の優先度

(<literal>"h"</literal> よりもっと長いキーに一致しているので、この置換は行われていないこと)、

そして一度置換した文字列はもう置換の対象にならないことを確認しましょう。

</para>

<example>

<title>2 つの引数を伴う <function>strtr</function> の例</title>

<programlisting role="php">

<![CDATA[

<?php

$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");

echo strtr("hi all, I said hello", $trans);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

hello all, I said hi

]]>

</screen>

</example>

<para>

これらふたつのモードの挙動は大きく異なります。引数が三つの場合は

<function>strtr</function> はバイト単位で置換し、二つの場合はより長い部分文字列を置換します。

</para>

<example>

<title><function>strtr</function> の挙動の比較</title>

<programlisting role="php">

<![CDATA[

<?php

echo strtr("baab", "ab", "01"),"\n";

$trans = array("ab" => "01");

echo strtr("baab", $trans);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

1001

ba01

]]>

</screen>

</example>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>str_replace</function></member>

<member><function>preg_replace</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->