svn: /phpdoc/en/trunk/reference/strings/functions/ str-ireplace.xml str-replace.xml

aharvey Fri, 07 Jan 2011 03:39:17 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=307205 Log: Fix doc bug #53678 (Formatting Suggestion: "count" parameter). Also fix up the str_ireplace() manual page, which seems to have lost paragraphs here and there for some reason, by copying verbiage across from the str_replace() page and changing it as required, and fix a grammatical error in the paragraph about using arrays as search and replacement values. Bug: http://bugs.php.net/53678 (Assigned) Formatting Suggestion: "count" parameter Changed paths: U phpdoc/en/trunk/reference/strings/functions/str-ireplace.xml U phpdoc/en/trunk/reference/strings/functions/str-replace.xml Modified: phpdoc/en/trunk/reference/strings/functions/str-ireplace.xml =================================================================== --- phpdoc/en/trunk/reference/strings/functions/str-ireplace.xml 2011-01-07 01:30:03 UTC (rev 307204) +++ phpdoc/en/trunk/reference/strings/functions/str-ireplace.xml 2011-01-07 03:39:17 UTC (rev 307205) @@ -28,22 +28,38 @@ <refsect1 role="parameters"> &reftitle.parameters; <para> + If <parameter>search</parameter> and <parameter>replace</parameter> are + arrays, then <function>str_ireplace</function> takes a value from each + array and uses them to 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> + If <parameter>search</parameter> or <parameter>replace</parameter> + are arrays, their elements are processed first to last. + </para> + <para> <variablelist> <varlistentry> <term><parameter>search</parameter></term> <listitem> - <note> - <para> - Every replacement with <parameter>search</parameter> array is - performed on the result of previous replacement. - </para> - </note> + <para> + The value being searched for, otherwise known as the + <emphasis>needle</emphasis>. An array may be used to designate + multiple needles. + </para> </listitem> </varlistentry> <varlistentry> <term><parameter>replace</parameter></term> <listitem> <para> + The replacement value that replaces found <parameter>search</parameter> + values. An array may be used to designate multiple replacements. </para> </listitem> </varlistentry> @@ -51,6 +67,10 @@ <term><parameter>subject</parameter></term> <listitem> <para> + The string or array being searched and replaced on, + otherwise known as the <emphasis>haystack</emphasis>. + </para> + <para> If <parameter>subject</parameter> is an array, then the search and replace is performed with every entry of <parameter>subject</parameter>, and the return value is an array as @@ -62,25 +82,12 @@ <term><parameter>count</parameter></term> <listitem> <para> - The number of matched and replaced <parameter>needles</parameter> will - be returned in <parameter>count</parameter> which is passed by - reference. + If passed, this will be set to the number of replacements performed. </para> </listitem> </varlistentry> </variablelist> </para> - <para> - If <parameter>search</parameter> and <parameter>replace</parameter> are - arrays, then <function>str_ireplace</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>. - </para> </refsect1> <refsect1 role="returnvalues"> @@ -133,6 +140,14 @@ <refsect1 role="notes"> &reftitle.notes; &note.bin-safe; + <caution> + <title>Replacement order gotcha</title> + <para> + Because <function>str_ireplace</function> replaces left to right, it might + replace a previously inserted value when doing multiple replacements. See + also the examples in this document. + </para> + </caution> </refsect1> <refsect1 role="seealso"> Modified: phpdoc/en/trunk/reference/strings/functions/str-replace.xml =================================================================== --- phpdoc/en/trunk/reference/strings/functions/str-replace.xml 2011-01-07 01:30:03 UTC (rev 307204) +++ phpdoc/en/trunk/reference/strings/functions/str-replace.xml 2011-01-07 03:39:17 UTC (rev 307205) @@ -31,14 +31,14 @@ &reftitle.parameters; <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. + arrays, then <function>str_replace</function> takes a value from each array + and uses them to 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> If <parameter>search</parameter> or <parameter>replace</parameter> @@ -82,11 +82,9 @@ <varlistentry> <term><parameter>count</parameter></term> <listitem> - <note> - <simpara> - If passed, this will hold the number of matched and replaced needles. - </simpara> - </note> + <para> + If passed, this will be set to the number of replacements performed. + </para> </listitem> </varlistentry> </variablelist>