str-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b Maintainer: sammywg Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.str-replace" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>str_replace</refname>
  <refpurpose>Ersetzt alle Vorkommen des Suchstrings durch einen anderen String</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>array</type></type><methodname>str_replace</methodname>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>search</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>replace</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Diese Funktion gibt einen String oder ein Array zurück, in dem alle
   Vorkommen von <parameter>search</parameter> innerhalb von
   <parameter>subject</parameter> durch den angegebenen
   <parameter>replace</parameter>-Wert ersetzt wurden.
  </para>
  <para>
   Um Text anhand eines Musters statt einer konkreten Zeichenkette zu
   ersetzen, kann <function>preg_replace</function> verwendet werden.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Sind <parameter>search</parameter> und <parameter>replace</parameter>
   Arrays, nimmt <function>str_replace</function> je einen Wert beider Arrays
   und verwendet diese zum Suchen und Ersetzen in
   <parameter>subject</parameter>. Hat <parameter>replace</parameter> weniger
   Werte als <parameter>search</parameter>, so wird ein leerer String zum
   Ersetzen für den Rest der Werte verwendet. Ist
   <parameter>search</parameter> ein Array und <parameter>replace</parameter>
   ein String, dann wird dieser String für jeden Wert von
   <parameter>search</parameter> angewandt. Das Gegenteil ist nicht sinnvoll.
  </para>
  <para>
   Sind <parameter>search</parameter> und/oder <parameter>replace</parameter>
   Arrays, werden ihre Elemente vom ersten zum letzten hin verarbeitet.
  </para>
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>search</parameter></term>
     <listitem>
      <para>
       Der gesuchte Wert, auch <emphasis>Nadel (needle)</emphasis> genannt.
       Ein Array kann genutzt werden, um mehrere Nadeln zu bestimmen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replace</parameter></term>
     <listitem>
      <para>
       Der Ersetzungswert, der gefundene <parameter>search</parameter> Werte
       ersetzt. Ein Array kann genutzt werden, um mehrere Werte zu bestimmen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Die zu durchsuchende und darin enthaltene zu ersetzende Zeichenkette
       oder das Array, auch <emphasis>Heuhaufen (haystack)</emphasis> genannt.
      </para>
      <para>
       Ist <parameter>subject</parameter> ein Array, erfolgt das Suchen und
       Ersetzen für jeden Wert von <parameter>subject</parameter>, und der
       Rückgabewert ist ebenfalls ein Array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>count</parameter></term>
     <listitem>
      <para>
       Falls übergeben, wird dies auf die Anzahl der durchgeführten
       Ersetzungen gesetzt.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Diese Funktion gibt eine Zeichenkette oder ein Array mit ersetzten Werten
   zurück.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Grundlegende <function>str_replace</function>-Beispiele</title>
    <programlisting role="php">
<![CDATA[
<?php
// Liefert: <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
echo $bodytag, PHP_EOL;

// Liefert: Hll PHP-Wlt
$vokale = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$nurkonsonanten = str_replace($vokale, "", "Hallo PHP-Welt");
echo $nurkonsonanten, PHP_EOL;

// Liefert: Sie sollten taeglich Pizza, Bier und Eiscreme essen.
$satz = "Sie sollten taeglich Fruechte, Gemuese und Ballaststoffe essen.";
$gesund = array("Fruechte", "Gemuese", "Ballaststoffe");
$lecker = array("Pizza", "Bier", "Eiscreme");

$neuersatz = str_replace($gesund, $lecker, $satz);
echo $neuersatz, PHP_EOL;

// Liefert: 2
$str = str_replace("ll", "", "good golly miss molly!", $anzahl);
echo $anzahl, PHP_EOL;
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Beispiele möglicher Probleme durch <function>str_replace</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Reihenfolge von Ersetzungen
$str     = "Zeile 1\nZeile 2\rZeile 3\r\nZeile 4\n";
$order   = array("\r\n", "\n", "\r");
$replace = '<br />';
// Verarbeitet \r\n's zuerst, so dass sie nicht doppelt konvertiert werden
$newstr = str_replace($order, $replace, $str);
echo $newstr, PHP_EOL;

// Ausgabe: F da A durch B ersetzt wird, dann B durch C, und so weiter...
// Letztlich wird E durch F ersetzt, wegen der Ersetzung von Links nach Rechts
$search  = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject), PHP_EOL;

// Ausgabe: apearpearle pear
// Aus dem gleichen Grund wie oben beschrieben
$letters = array('a', 'p');
$fruit   = array('apple', 'pear');
$text    = 'a p';
$output  = str_replace($letters, $fruit, $text);
echo $output, PHP_EOL;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
  <caution>
   <title>Mögliche Probleme durch Reihenfolge der Ersetzungen</title>
   <para>
    Weil <function>str_replace</function> von links nach rechts ersetzt, kann
    ein zuvor eingesetzter Wert ersetzt werden, wenn mehrere Ersetzungen
    durchgeführt werden. Das letzte Beispiel zeigt, was dies für Auswirkungen
    hat.
   </para>
  </caution>
  <note>
   <para>
    Die Funktion berücksichtigt Groß- und Kleinschreibung. Verwenden Sie
    <function>str_ireplace</function>, wenn Sie unabhängig von Groß- und
    Kleinschreibung ersetzen möchten.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>str_ireplace</function></member>
    <member><function>substr_replace</function></member>
    <member><function>preg_replace</function></member>
    <member><function>strtr</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
-->