From 6df83eb27dbe77b72ec56173a00e254294570c78 Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Mon, 22 Jan 2001 21:48:59 +0000
Subject: [PATCH] Docs for str_replace() improvements.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@39992 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/strings.xml | 49 ++++++++++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/functions/strings.xml b/functions/strings.xml
index 32cfd80ec7..f3d5199436 100644
--- a/functions/strings.xml
+++ b/functions/strings.xml
@@ -2944,28 +2944,49 @@ print $str; # Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
    <refnamediv>
     <refname>str_replace</refname>
     <refpurpose>
-     Replace all occurrences of needle in haystack with str
+     Replace all occurrences of the search string in subject with the replacement string
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
-      <funcdef>string <function>str_replace</function></funcdef>
-      <paramdef>string <parameter>needle</parameter></paramdef>
-      <paramdef>string <parameter>str</parameter></paramdef>
-      <paramdef>string <parameter>haystack</parameter></paramdef>
+      <funcdef>mixed <function>str_replace</function></funcdef>
+      <paramdef>mixed <parameter>search</parameter></paramdef>
+      <paramdef>mixed <parameter>replace</parameter></paramdef>
+      <paramdef>mixed <parameter>subject</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
-     This function replaces all occurences of
-     <parameter>needle</parameter> in <parameter>haystack</parameter>
-     with the given <parameter>str</parameter>. If you don't need
-     fancy replacing rules, you should always use this function
-     instead of <function>ereg_replace</function>.</para>
+     This function replaces all occurences of <parameter>search</parameter> in
+     <parameter>subject</parameter> with the given
+     <parameter>replace</parameter> value.  If you don't need fancy replacing
+     rules, you should always use this function instead of
+     <function>ereg_replace</function> or
+     <function>preg_replace</function>.</para>
+    <para>
+     In PHP 4.0.5 and later, every parameter to
+     <function>str_replace</function> can be an array.
+    </para>
+    <para>
+     If <parameter>subject</parameter> is an array, then the search and replace
+     is performed on every entry of <parameter>subject</parameter>, and the
+     return value is an array as well.
+    </para>
+    <para>
+     If <parameter>search</parameter> and <parameter>replace</parameter> are
+     arrays, then <function>str_replace</function> takes a value from each
+     array and uses them to do search and replace on
+     <parameter>subject</parameter>.  If <parameter>replace</parameter> has
+     fewer values than <parameter>search</parameter>, then an empty string is
+     used for the rest of replacement values.  If <parameter>search</parameter>
+     is an array and <parameter>replace</parameter> is a string; then this
+     replacement string is used for every value of
+     <parameter>search</parameter>.  The converse would not make sense, though.
+    </para>
     <para>
      <example>
-      <title><function>Str_replace</function> example</title>
+      <title><function>str_replace</function> example</title>
       <programlisting role="php">
 $bodytag = str_replace ("%body%", "black", "&lt;body text=%body%>");
       </programlisting>
@@ -2976,13 +2997,13 @@ $bodytag = str_replace ("%body%", "black", "&lt;body text=%body%>");
     </para>
     <note>
      <para>
-      <function>Str_replace</function> was added in PHP 3.0.6, but was
+      <function>str_replace</function> was added in PHP 3.0.6, but was
       buggy up until PHP 3.0.8.
      </para>
     </note>
     <para>
-     See also <function>ereg_replace</function> and
-     <function>strtr</function>.
+     See also <function>ereg_replace</function>,
+     <function>preg_replace</function>, and <function>strtr</function>.
     </para>
    </refsect1>
   </refentry>