preg-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 62126c55f1c6ed444043e7272c4f9e233818a44b Maintainer: takagi Status: ready -->
<!-- Credits: hirokawa,haruki,shimooka,mumumu -->
<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から）カウントされます。
       &string; に含まれるバックスラッシュリテラルは、エスケープが必須であることに注意して下さい。
      </para>
      <para>
       後方参照の直後に他の数字が続くような置換 (replacement) パターンを
       使用する場合（すなわち、マッチしたパターンの直後に数字リテラルを置く
       場合）、後方参照を行うために通常の <literal>\1</literal> 表記を
       使用することができません。例えば、<literal>\11</literal>　は、
       後方参照 <literal>\1</literal> の後にリテラル
       <literal>1</literal> が続くのか、後方参照 <literal>\11</literal> で
       その後には何も続かないのかが不明のため、
       <function>preg_replace</function> を混乱させる可能性があります。
       この場合、解決策は、<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> を意識し、
       文字列がどのように解釈されるのかを正確に知っておくようにしましょう。
      </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>
   "\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>添字配列の使用</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>
     pattern と replacement を ksort すると、所望のものが得られます。
    </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);
// This will be 'foo o' now
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'));
// prints 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
-->