str_replace

(PHP 4, PHP 5)

str_replace — Заменяет все вхождения строки поиска на строку замены

Описание

mixed str_replace ( mixed $search , mixed $replace , mixed $subject [, int &$count ] )

Эта функция возвращает строку или массив, в котором все вхождения search в subject заменены на replace.

Если не нужны сложные правила поиска/замены (например, регулярные выражения), использование этой функции предпочтительнее preg_replace().

Список параметров

Если search и replace - массивы, то str_replace() использует каждое значение из соответствующего массива для поиска и замены в subject. Если в массиве replace меньше элементов, чем в search, в качестве строки замены для оставшихся значений будет использована пустая строка. Если search - массив, а replace - строка, то эта строка замены будет использована для каждого элемента массива search. Обратный случай смысла не имеет.

Если search или replace являются массивами, их элементы будут обработаны от первого к последнему.

search

Искомое значение, также известное как needle (иголка). Для множества искомых значений можно использовать массив.

replace

Значение замены, будет использовано для замены искомых значений search. Для множества значений можно использовать массив.

subject

Строка или массив, в котором производится поиск и замена, также известный как haystack (стог сена).

Если subject является массивом, то поиск с заменой будет осуществляться над каждым элементом subject, а результатом функции также будет являться массив.

count

Если передан, то будет установлен в количество произведенных замен.

Возвращаемые значения

Эта функция возвращает строку или массив с замененными значениями.

Список изменений

Версия	Описание
5.0.0	Добавлен параметр `count`.
4.3.3	Поведение этой функции изменилось. В старых версиях существовала ошибка при одновременной передаче массивов в аргументах `search` и `replace`. Ошибка заключается в том, что пустые элементы массива `search` пропускались без перемещения к следующему элементу массива `replace`. Эта ошибка была исправлена в PHP 4.3.3. Если ваши скрипты использовали эту ошибку, то в них нужно удалить пустые элементы из массива search перед вызовом этой функции.
4.0.5	Большинство параметров теперь могут принимать тип array.

Примеры

Пример #1 Примеры использования str_replace()


<?php
// присваивает <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");

// присваивает: Hll Wrld f PHP
$vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$onlyconsonants = str_replace($vowels, "", "Hello World of PHP");

// присваивает: You should eat pizza, beer, and ice cream every day
$phrase  = "You should eat fruits, vegetables, and fiber every day.";
$healthy = array("fruits", "vegetables", "fiber");
$yummy   = array("pizza", "beer", "ice cream");

$newphrase = str_replace($healthy, $yummy, $phrase);

// присваивает: 2
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count;
?>

Пример #2 Примеры потенциальных трюков с str_replace()


<?php
// Порядок замены
$str     = "Строка 1\nСтрока 2\rСтрока 3\r\nСтрока 4\n";
$order   = array("\r\n", "\n", "\r");
$replace = '<br />';

// Обрабатывает сначала \r\n для избежания их повторной замены.
echo $newstr = str_replace($order, $replace, $str);

// Выводит F, т.к. A заменяется на B, затем B на C, и так далее...
// В итоге E будет заменено F, так как замена происходит слева направо.
$search  = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject);

// Выводит: яблорехкорех орех (по вышеуказанной причине)
$letters = array('я', 'о');
$fruit   = array('яблоко', 'орех');
$text    = 'я о';
$output  = str_replace($letters, $fruit, $text);
echo $output;
?>

Примечания

Замечание: Эта функция безопасна для обработки данных в двоичной форме.

Предостережение

Замечание о порядке замены

Так как str_replace() осуществляет замену слева направо, то при использовании множественных замен она может заменить ранее вставленное значение на другое. Смотрите также примеры на этой странице.

Замечание:
Эта функция чувствительна к регистру. Используйте str_ireplace() для замены, нечувствительной к регистру.

Смотрите также

str_ireplace() - Регистро-независимый вариант функции str_replace
substr_replace() - Заменяет часть строки
preg_replace() - Выполняет поиск и замену по регулярному выражению
strtr() - Преобразует заданные символы или заменяет подстроки