strtr

(PHP 4, PHP 5, PHP 7, PHP 8)

strtr — 文字の変換あるいは部分文字列の置換を行う

説明

function strtr(string $string, string $from, string $to): string

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

function strtr(string $string, array $replace_pairs): string

引数を三つ渡した場合、この関数は string のコピーを返します。その際に、文字列中に from の各文字 (シングルバイト) があれば to の対応する文字に変換します。つまり、すべての $from[$n] が $to[$n] に置換されることになります。ここで $n は、どちらの引数でも共通に有効なオフセットです。

from と to の長さが異なる場合、長い方の余分な文字は無視されます。返される文字列の長さは、もとの string と同じになります。

引数を二つだけ渡す場合は、二番目の引数を array('from' => 'to', ...) 形式の配列にしなければなりません。返される値は文字列で、もとの文字列中にある配列のキーと同じ部分を対応する値で置換したものとなります。一番長いキーから順に調べます。一度部分文字列の置換を行うと、置換後の文字列がさらに置換の対象となることはありません。

この場合は、配列のキーと値は任意の長さにすることができますが、キーを空にすることだけはできません。さらに、返される文字列の長さはもとの string とは異なる可能性があります。しかし、この関数が最も効率的に働くのは、すべてのキーが同じ長さである場合です。

パラメータ

string

変換する文字列。

from

to に変換される文字列。

to

from を置換する文字列。

replace_pairs

replace_pairs パラメータを to や from のかわりに使用することができます。この場合は array('from' => 'to', ...) 形式の配列となります。

replace_pairs の中に空文字列 ("") のキーがある場合は、その要素は無視されます。 PHP 8.0.0 以降では、この場合 E_WARNING が発生します。

戻り値

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

例

例1 strtr() の例

<?php

$original = "He1Lo, w0rld!";

// 引数を三つ渡した場合、strtr() はバイト単位での変換を行います。
$result = strtr($original, "1L0", "llo");
echo $result;

上の例の出力は以下となります。

Hello, world!

次の例は、引数を二つだけ指定して strtr() をコールしたときの挙動を示すものです。置換の優先度 ("h" よりもっと長いキーに一致しているので、この置換は行われていないこと)、そして一度置換した文字列はもう置換の対象にならないことを確認しましょう。

例2 2 つの引数を伴う strtr() の例

<?php

$replace_pairs = ["h" => "-", "hello" => "hi", "hi" => "hello"];
echo strtr("hi all, I said hello", $replace_pairs);

上の例の出力は以下となります。

hello all, I said hi

これらふたつのモードの挙動は大きく異なります。引数が三つの場合は strtr() はバイト単位で置換し、二つの場合はより長い部分文字列を置換します。

例3 strtr() の挙動の比較

<?php

// シングルバイト文字
$singlebyte_string = "baab";
echo strtr($singlebyte_string, "ab", "01"), "\n"; // バイト単位での変換

$replace_pairs = ["ab" => "01"];
echo strtr($singlebyte_string, $replace_pairs), "\n"; // 部分文字列の置換

// マルチバイト文字
$multibyte_string = "Ä"; // UTF-8 では 2 バイト "\xC3\x84" にエンコードされます

$result = strtr($multibyte_string, 'Ä', 'A');
echo bin2hex($result), "\n"; // "4184"。"c3" が "41" ("A") になり、"84" はそのまま残るので UTF-8 として壊れます

$replace_pairs = ['Ä' => 'A'];
echo strtr($multibyte_string, $replace_pairs); // マルチバイト文字列に対する正しい部分文字列の置換

上の例の出力は以下となります。

参考

str_replace() - 検索文字列に一致したすべての文字列を置換する
preg_replace() - 正規表現検索および置換を行う