preg-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d6f54016d62904cfd8200604aadd5e3f0d9bad97 Maintainer: samesch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.preg-replace" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_replace</refname>
  <refpurpose>Sucht und ersetzt mit regulären Ausdrücken</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>
   Durchsucht die Zeichenkette <parameter>subject</parameter> nach
   Übereinstimmungen mit <parameter>pattern</parameter> und ersetzt sie mit
   <parameter>replacement</parameter>.
  </para>
  <para>
   Um eine konkrete Zeichenkette anstelle eines Musters zu finden, sollte
   <function>str_replace</function> oder <function>str_ireplace</function>
   anstelle dieser Funktion verwendet werden.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
       Der Ausdruck, nach dem gesucht wird. Es kann entweder eine Zeichenkette
       oder ein Array mit Zeichenketten sein.
      </para>
      <para>
       Es stehen auch einige
       <link linkend="reference.pcre.pattern.modifiers">PCRE-Modifikatoren</link>
       zur Verfügung.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replacement</parameter></term>
     <listitem>
      <para>
       Die Zeichenkette oder das Array mit Zeichenketten zum Ersetzen. Falls
       dieser Parameter eine Zeichenkette ist und der Parameter
       <parameter>pattern</parameter> ein Array, werden alle Suchmuster durch
       diese Zeichenkette ersetzt. Falls sowohl <parameter>pattern</parameter>
       als auch <parameter>replacement</parameter> Arrays sind, wird jedes
       Suchmuster <parameter>pattern</parameter> durch das Gegenstück aus
       <parameter>replacement</parameter> ersetzt. Wenn das
       <parameter>replacement</parameter>-Array weniger Elemente hat als das
       <parameter>pattern</parameter>-Array, wird jedes überzählige
       <parameter>pattern</parameter> durch die leere Zeichenkette ersetzt.
      </para>
      <para>
       <parameter>replacement</parameter> darf Referenzen in der Form
       <literal>\<replaceable>n</replaceable></literal> oder
       <literal>$<replaceable>n</replaceable></literal> enthalten, wobei
       Letztere vorzuziehen ist. Jede dieser Referenzen wird mit dem Text
       ersetzt, der vom <replaceable>n</replaceable>-ten eingeklammerten
       Suchmuster erfasst wurde. <replaceable>n</replaceable> kann einen Wert
       von 0 bis 99 haben. <literal>\0</literal> oder <literal>$0</literal>
       beziehen sich auf den Text, der auf das komplette Suchmuster passt. Um
       die Nummer des erfassenden Teil-Suchmusters zu erhalten, werden
       öffnende Klammern mit 1 beginnend von links nach rechts gezählt. Es ist
       zu beachten, dass Rückwärtsschrägstriche in &string;-Literalen ggf.
       maskiert werden müssen.
      </para>
      <para>
       Wenn Sie mit einer Ersetzung arbeiten wollen, in der auf eine
       Rückreferenzierung direkt eine weitere Zahl folgt (&dh; direkt nach
       der Übereinstimmmung mit einem Suchmuster soll eine Zahl kommen),
       können Sie für Ihre Rückreferenzierung nicht die Schreibweise
       <literal>\1</literal> verwenden. So würde &zb; <literal>\11</literal>
       die Funktion <function>preg_replace</function> verwirren, weil sie
       nicht weiß, ob Sie die Rückreferenzierung <literal>\1</literal> gefolgt
       von der Zahl <literal>1</literal> wollen oder nur die
       Rückreferenzierung <literal>\11</literal>. In diesem Fall ist die
       Lösung, <literal>${1}1</literal> zu verwenden. Damit wird eine
       isolierte Rückreferenzierung <literal>$1</literal> erzeugt und die
       <literal>1</literal> bleibt ein Buchstabensymbol.
      </para>
      <para>
       Wenn Sie den veralteten Modifikator <literal>e</literal> verwenden,
       maskiert diese Funktion ein paar Zeichen (nämlich <literal>'</literal>,
       <literal>"</literal>, <literal>\</literal> und NULL) in den
       Zeichenketten, mit denen die Rückreferenzierungen ersetzen werden. Das
       wird gemacht, um sicherzustellen, dass keine Syntaxfehler entstehen,
       wenn Rückreferenzierungen verwendet werden, die einfache oder doppelte
       Anführungszeichen enthalten (&zb;
       <literal>'strlen(\'$1\')+strlen("$2")'</literal>). Vergewissern Sie
       sich, dass Sie die
       <link linkend="language.types.string">Zeichenketten-Syntax</link> von
       PHP kennen, um genau zu wissen, wie die ausgewertete Zeichenkette
       aussieht.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Die Zeichenkette oder ein Array mit Zeichenketten zum Durchsuchen.
      </para>
      <para>
       Falls <parameter>subject</parameter> ein Array ist, wird das Suchen und
       Ersetzen auf jedes Element von <parameter>subject</parameter> angewandt
       und der Rückgabewert ist ebenfalls ein Array.
      </para>
      <para>
       Wenn das <parameter>subject</parameter>-Array assoziativ ist, bleiben
       die Schlüssel im zurückgegebenen Wert erhalten.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
       Die maximal mögliche Anzahl von Ersetzungen für jedes Suchmuster in
       jeder <parameter>subject</parameter>. Standardmäßiger Wert:
       <literal>-1</literal> (kein Limit).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>count</parameter></term>
     <listitem>
      <para>
       Falls angegeben, wird dieser Variable die Anzahl vorgenommener
       Ersetzungen zugewiesen.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>preg_replace</function> gibt ein Array zurück, falls
   <parameter>subject</parameter> ein Array ist, andernfalls eine
   Zeichenkette.
  </para>
  <para>
   Falls Übereinstimmungen gefunden wurden, wird die neue Zeichenkette
   <parameter>subject</parameter> zurückgegeben, andernfalls wird
   <parameter>subject</parameter> unverändert zurückgegeben oder &null;, falls
   ein Fehler auftrat.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Die Verwendung des Modifikators "\e" führt zu einem Fehler der Stufe
   <constant>E_WARNING</constant>.
  </para>
  &pcre.pattern.warning;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Die Verwendung von Rückreferenzierungen mit darauf folgenden numerischen
     Literalen
    </title>
    <programlisting role="php">
<![CDATA[
<?php
$zeichenkette = '15. April 2003';
$suchmuster = '/(\d+)\. (\w+) (\d+)/i';
$ersetzung = '${2}1,$3';
echo preg_replace($suchmuster, $ersetzung, $zeichenkette);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
April1,2003
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     Die Verwendung von <function>preg_replace</function> mit indizierten
     Arrays
    </title>
    <programlisting role="php">
<![CDATA[
<?php
$zeichenkette = 'Der schnelle braune Fuchs springt über den faulen Hund.';

$suchmuster = array();
$suchmuster[0] = '/schnelle/';
$suchmuster[1] = '/braune/';
$suchmuster[2] = '/Fuchs/';

$ersetzungen = array();
$ersetzungen[2] = 'Bär';
$ersetzungen[1] = 'schwarze';
$ersetzungen[0] = 'langsame';

echo preg_replace($suchmuster, $ersetzungen, $zeichenkette);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Der Bär schwarze langsame springt über den faulen Hund.
]]>
    </screen>
    <para>
     Wenn wir Suchmuster und Ersetzungen mit <function>ksort</function>
     sortieren, sollten wir bekommen, was wir wollten.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$zeichenkette = 'Der schnelle braune Fuchs springt über den faulen Hund.';
$suchmuster = array();
$suchmuster[0] = '/schnelle/';
$suchmuster[1] = '/braune/';
$suchmuster[2] = '/Fuchs/';
$ersetzungen = array();
$ersetzungen[2] = 'Bär';
$ersetzungen[1] = 'schwarze';
$ersetzungen[0] = 'langsame';
ksort($suchmuster);
ksort($ersetzungen);
echo preg_replace($suchmuster, $ersetzungen, $zeichenkette);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Der langsame schwarze Bär springt über den faulen Hund.
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Ersetzen mehrerer Werte</title>
    <programlisting role="php">
<![CDATA[
<?php
$suchmuster = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
                     '/^\s*{(\w+)}\s*=/');
$ersetzen = array ('\4.\3.\1\2', '$\1 =');
echo preg_replace($suchmuster, $ersetzen, '{startDatum} = 1999-5-27');
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
$startDatum = 27.5.1999
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Leerzeichen entfernen</title>
    <para>
     Dieses Beispiel entfernt überschüssige Leerzeichen aus einer
     Zeichenkette.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'foo   o';
$str = preg_replace('/\s\s+/', ' ', $str);
// Das ist jetzt 'foo o'
echo $str;
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Die Verwendung des Parameters <parameter>count</parameter></title>
    <programlisting role="php">
<![CDATA[
<?php
$anzahl = 0;

echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $anzahl);
echo $anzahl; //3
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
xp***to
3
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Bei der Verwendung von Arrays für <parameter>pattern</parameter> und
    <parameter>replacement</parameter> werden die Schlüssel in der Reihenfolge
    bearbeitet, in der sie im Array vorliegen. Das ist <emphasis>nicht
    notwendigerweise</emphasis> dieselbe, wie die numerische Reihenfolge der
    Indizes. Wenn Indizes verwendet werden, um festzulegen welches
    <parameter>pattern</parameter> durch welchen Ersatz
    <parameter>replacement</parameter> ersetzt werden soll, sollte vor dem
    Aufruf von <function>preg_replace</function> <function>ksort</function>
    auf jedes Array angewendet werden.
   </para>
  </note>
  <note>
   <para>
    Wenn sowohl <parameter>pattern</parameter> als auch
    <parameter>replacement</parameter> Arrays sind, werden die
    Übereinstimmungsregeln nacheinander angewendet. Das heißt, das zweite
    <parameter>pattern</parameter>/<parameter>replacement</parameter>-Paar
    wirkt nicht auf die ursprüngliche Zeichenkette, sondern auf die
    Zeichenkette, die sich aus dem ersten
    <parameter>pattern</parameter>/<parameter>replacement</parameter>-Paar
    ergibt. Um parallele Ersetzungen zu simulieren, &zb; das Vertauschen von
    zwei Werten, muss ein Muster durch einen zwischengeschalteten Platzhalter
    ersetzt werden, der dann in einem späteren Paar durch die gewünschte
    Ersetzung ersetzt wird.
   </para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// Gibt d aus
?>
]]>
    </programlisting>
   </informalexample>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="pcre.pattern">PCRE-Suchmuster</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
-->