preg-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 62126c55f1c6ed444043e7272c4f9e233818a44b Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.preg-replace" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_replace</refname>
  <refpurpose>Выполняет поиск и замену по регулярному выражению</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>array</type><type>null</type></type><methodname>preg_replace</methodname>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>pattern</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>replacement</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Функция ищет в строке <parameter>subject</parameter> совпадения
   с шаблоном <parameter>pattern</parameter> и заменяет совпадения
   на значение <parameter>replacement</parameter>.
  </para>
  <para>
   Вместо этой функции обращаются к функциям <function>str_replace</function>
   или <function>str_ireplace</function>, когда требуется найти соответствие точной
   строке, а не шаблону.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
       Искомый шаблон: строка или массив строк.
      </para>
      <para>
       В шаблоне также указывают
       <link linkend="reference.pcre.pattern.modifiers">
        модификаторы модуля PCRE
       </link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replacement</parameter></term>
     <listitem>
      <para>
       Строка или массив строк, в которых функция будет искать
       и заменять совпадения.

       Эта строка заменит каждую подстроку входной строки,
       которая совпала с шаблоном, если в этот параметр передали строку,
       а в параметр <parameter>pattern</parameter> — массив.

       Функция заменит каждую подстроку, которая совпала
       c шаблоном в массиве <parameter>pattern</parameter>,
       на значение <parameter>replacement</parameter> с тем же
       смещением внутреннего указателя массива, что и у шаблона,
       если и параметр <parameter>pattern</parameter>,
       и параметр <parameter>replacement</parameter> — массивы.

       Функция заменит на пустую строку каждую подстроку,
       которая совпала с лишним шаблоном в массиве <parameter>pattern</parameter>,
       если массив <parameter>replacement</parameter> содержит
       меньше элементов, чем массив <parameter>pattern</parameter>.
      </para>
      <para>
       В параметре <parameter>replacement</parameter> разрешается указывать ссылки вида
       <literal>\<replaceable>n</replaceable></literal>
       или <literal>$<replaceable>n</replaceable></literal>,
       причём лучше предпочесть последний вариант. Каждую такую ссылку
       функция заменит на подстроку, которую захватил
       <replaceable>n</replaceable>-й подшаблон в круглых скобках.

       Номер группы <replaceable>n</replaceable> принимает значения от 0
       до 99, причём ссылки <literal>\0</literal> или <literal>$0</literal>
       соответствует вхождению всего шаблона.

       Открывающие подшаблон скобки нумеруются слева направо, начиная с единицы,
       и указывают на номер подшаблона захвата.

       Обратите внимание, в отдельных ситуациях обратные слеши в строковых (&string;)
       литералах требуют экранирования.
      </para>
      <para>
       Когда при работе с шаблоном замены за обратной ссылкой сразу идёт другое число
       (то есть буквальное число идёт сразу после подстроки, которая совпала с шаблоном),
       для ссылки на подшаблон нельзя использовать знакомую нотацию вида <literal>\1</literal>.
       Например, запись <literal>\11</literal> собьёт функцию <function>preg_replace</function>
       с толку, поскольку функция не знает, требуется ли выбрать первую обратную ссылку <literal>\1</literal>,
       за которой идёт буквальная цифра <literal>1</literal>,
       или требуется выбрать одиннадцатую обратную ссылку <literal>\11</literal>,
       за которой ничего не идёт.

       Решение состоит в том, чтобы использовать конструкцию <literal>${1}1</literal>,
       которая создаёт изолированную обратную ссылку <literal>$1</literal>,
       а число <literal>1</literal> оставляет литералом.
      </para>
      <para>
       Если в шаблоне указали устаревший модификатор <literal>e</literal>,
       функция заэкранирует в строках, которыми замещаются обратные ссылки,
       отдельные символы: <literal>'</literal>, <literal>"</literal>, <literal>\</literal> и NULL.
       Это сделали, чтобы гарантировать отсутствие синтаксических ошибок
       при записи обратных ссылок в одинарных или двойных кавычках:
       <literal>'strlen(\'$1\')+strlen("$2")'</literal>.
       Знание <link linkend="language.types.string">синтаксиса записи строк</link>
       в PHP помогает понять, как интерпретатор будет видеть строку.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Строка или массив строк для поиска и замены.
      </para>
      <para>
       Функция найдёт и заменит каждый элемент массива <parameter>subject</parameter>,
       а затем вернёт массив,
       если в параметр <parameter>subject</parameter> передали массив.
      </para>
      <para>
       Функция сохранит ключи в массиве с результатами,
       если в параметр <parameter>subject</parameter> передали ассоциативный массив.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
       Максимальное количество замен каждого шаблона
       для каждой строки <parameter>subject</parameter>.
       Значение по умолчанию равно <literal>-1</literal> —
       не ограничивать количество замен.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>count</parameter></term>
     <listitem>
      <para>
       Функция заполнит эту переменную количеством замен, которые она выполнила,
       если переменную указали.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Функция <function>preg_replace</function> возвращает массив,
   если в параметр <parameter>subject</parameter> передали массив,
   иначе возвращается строка.
  </para>
  <para>
   Функция возвращает новую версию значения <parameter>subject</parameter>,
   если нашла совпадения,
   иначе значение <parameter>subject</parameter> возвращается нетронутым.
   Функция возвращает &null;, если возникла ошибка.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Функция выдаёт ошибку уровня <constant>E_WARNING</constant>,
   когда в шаблоне указывают модификатор \e.
  </para>
  &pcre.pattern.warning;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Пример обратных ссылок, за которыми следуют числовые литералы
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
April1,2003
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     Пример обработки функцией <function>preg_replace</function> индексных массивов
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$string = 'The quick brown fox jumps over the lazy dog.';

$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';

$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';

echo preg_replace($patterns, $replacements, $string);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
The bear black slow jumps over the lazy dog.
]]>
    </screen>
    <para>
     После сортировки шаблонов и замен по ключам получаем правильный результат:
    </para>
    <programlisting role="php">
<![CDATA[
<?php

ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
The slow black bear jumps over the lazy dog.
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Пример замены ряда значений по набору шаблонов</title>
    <programlisting role="php">
<![CDATA[
<?php

$patterns = array(
    '/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
    '/^\s*{(\w+)}\s*=/'
);

$replace = array('\3/\4/\1\2', '$\1 =');

echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
$startDate = 5/27/1999
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Пример удаления пробелов</title>
    <para>
     В этом примере функция удаляет из строки лишние пробелы.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$str = 'foo   o';
$str = preg_replace('/\s\s+/', ' ', $str);

// Теперь строка будет выглядеть вот так: 'foo o'
echo $str;

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>
     Пример с параметром <parameter>count</parameter>
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$count = 0;

echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; // 3

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
xp***to
3
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Функция обрабатывает ключи в том порядке, в котором ключи появляются в массиве,
    когда в параметры <parameter>pattern</parameter> и <parameter>replacement</parameter>
    передают массивы.
    Порядок ключей в этих массивах — <emphasis>не то же</emphasis>,
    что порядок числовых индексов.
    Если индексы требуются, чтобы определить,
    какой шаблон <parameter>pattern</parameter> требуется заменить
    какой заменой <parameter>replacement</parameter>,
    перед тем как вызывать функцию <function>preg_replace</function>,
    на каждом массиве вызывают функцию <function>ksort</function>.
   </para>
  </note>
  <note>
   <para>
    Функция применяет правила сопоставления последовательно,
    если и в параметр <parameter>pattern</parameter>,
    и в параметр <parameter>replacement</parameter> передали массив.
    То есть, вторая пара <parameter>pattern</parameter>/<parameter>replacement</parameter>
    будет работать со строкой, которую функция получила в результате обработки
    первой пары <parameter>pattern</parameter>/<parameter>replacement</parameter>,
    а не с исходной строкой.
    Когда требуется сымитировать параллельные замены, например,
    чтобы поменять два значения местами, один шаблон заменяют промежуточным заполнителем,
    а затем в следующей паре заменяют этот промежуточный заполнитель нужной заменой.
   </para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php

$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');

print_r(preg_replace($p, $r, 'a'));
// Выводит: d

?>
]]>
    </programlisting>
   </informalexample>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="pcre.pattern">Регулярные выражения PCRE</link></member>
    <member><function>preg_quote</function></member>
    <member><function>preg_filter</function></member>
    <member><function>preg_match</function></member>
    <member><function>preg_replace_callback</function></member>
    <member><function>preg_split</function></member>
    <member><function>preg_last_error</function></member>
    <member><function>str_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
-->