preg-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d6f54016d62904cfd8200604aadd5e3f0d9bad97 Maintainer: daijie Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<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>
        是一个数组，那么所有的模式都使用这个字符串进行替换。如果 <parameter>pattern</parameter> 和 <parameter>replacement</parameter>
        都是数组，每个 <parameter>pattern</parameter> 使用 <parameter>replacement</parameter> 中对应的元素进行替换。如果
        <parameter>replacement</parameter> 中的元素比 <parameter>pattern</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>
        代表完整的模式匹配文本。捕获子组的序号计数方式为：代表捕获子组的左括号从左到右， 从1开始数。如果要在
        <parameter>replacement</parameter> 中使用反斜线，必须使用 4 个(<literal>"\\\\"</literal>，译注：因为这首先是 PHP
        的字符串，经过转义后，是两个，再经过正则表达式引擎后才被认为是一个原文反斜线)。
      </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>)。确保符合 PHP 的
        <link linkend="language.types.string">字符串语法</link>，并且符合 eval 语法。因为在完成替换后，引擎会将结果字符串作为 PHP 代码使用
        eval 方式进行评估并将返回值作为最终参与替换的字符串。
      </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>
    如果 <parameter>subject</parameter> 是一个数组，<function>preg_replace</function>
    返回一个数组，其他情况下返回一个字符串。
  </para>
  <para>
  如果匹配被查找到，替换后的 <parameter>subject</parameter> 被返回，其他情况下返回没有改变的
  <parameter>subject</parameter>。如果发生错误，返回 &null; 。
  </para>
 </refsect1>

  <refsect1 role="errors">
  &reftitle.errors;
  <para>
   "\e" 会并忽略，并产生
   <constant>E_WARNING</constant> 错误。
  </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>
    对模式和替换内容按 key 进行排序我们可以得到期望的结果。
    </para>
    <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';
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>时, 
   将会按照key在数组中出现的顺序进行处理. 这<emphasis>不一定</emphasis>和数组的索引顺序一致.
   如果你期望使用索引对等方式用<parameter>replacement</parameter>对<parameter>pattern</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>
    生成的字符串，而不是原始字符串。
    If you want to simulate replacements operating in parallel,
    such as swapping two values, replace one pattern by an intermediary placeholder, then in a
    later pair replace that intermediary placeholder with the desired replacement.
   </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
-->