nlopess Sun Mar 27 07:38:20 2005 EDT
Modified files:
/phpdoc/en/reference/pcre/functions preg-replace.xml
Log:
switch to new style and document the new count parameter
#an english reviewer wanted.. :)
http://cvs.php.net/diff.php/phpdoc/en/reference/pcre/functions/preg-replace.xml?r1=1.15&r2=1.16&ty=u
Index: phpdoc/en/reference/pcre/functions/preg-replace.xml
diff -u phpdoc/en/reference/pcre/functions/preg-replace.xml:1.15
phpdoc/en/reference/pcre/functions/preg-replace.xml:1.16
--- phpdoc/en/reference/pcre/functions/preg-replace.xml:1.15 Sat Mar 12
15:29:57 2005
+++ phpdoc/en/reference/pcre/functions/preg-replace.xml Sun Mar 27 07:38:19 2005
@@ -1,28 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.15 $ -->
+<!-- $Revision: 1.16 $ -->
<!-- splitted from ./en/functions/pcre.xml, last change in rev 1.2 -->
<refentry id="function.preg-replace">
<refnamediv>
<refname>preg_replace</refname>
<refpurpose>Perform a regular expression search and replace</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
+ <refsect1 role="description">
+ &reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>preg_replace</methodname>
<methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
<methodparam><type>mixed</type><parameter>replacement</parameter></methodparam>
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter
role="reference">count</parameter></methodparam>
</methodsynopsis>
<para>
Searches <parameter>subject</parameter> for matches to
<parameter>pattern</parameter> and replaces them with
- <parameter>replacement</parameter>. If
- <parameter>limit</parameter> is specified, then only
- <parameter>limit</parameter> matches will be replaced; if
- <parameter>limit</parameter> is omitted or is -1, then all
- matches are replaced.
+ <parameter>replacement</parameter>.
</para>
<para>
<parameter>Replacement</parameter> may contain references of the form
@@ -48,21 +45,191 @@
as a literal.
</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>
+ The <literal>e</literal> modifier makes <function>preg_replace</function>
+ treat the <parameter>replacement</parameter> parameter as PHP code after
+ the appropriate references substitution is done. Tip: make sure that
+ <parameter>replacement</parameter> constitutes a valid PHP code string,
+ otherwise PHP will complain about a parse error at the line containing
+ <function>preg_replace</function>.
+ </para>
+</refsect1>
+
+<refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ The pattern to search for. It can be either a string or an array with
+ strings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>replacement</parameter></term>
+ <listitem>
+ <para>
+ The string or an array with strings to replace. If this parameter is a
+ string and the <parameter>pattern</parameter> parameter is an array,
+ all pattens will be replaced by that string. If both
+ <parameter>pattern</parameter> and <parameter>replacement</parameter>
+ parameters are arrays, each <parameter>pattern</parameter> will be
+ replaced by the <parameter>replacement</parameter> counterpart. If
+ there are less keys in the <parameter>replacement</parameter> array
+ than in the <parameter>pattern</parameter> array, the excedent
+ <parameter>pattern</parameter>s will be replaced by an empty string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>subject</parameter></term>
+ <listitem>
+ <para>
+ The string or an array with strings to search and replace.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>limit</parameter></term>
+ <listitem>
+ <para>
+ The maximum possible replacements for each pattern in each
+ <parameter>subject</parameter> string. Defaults to
+ <literal>-1</literal> (no limit).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>count</parameter></term>
+ <listitem>
+ <para>
+ If specified, this variable will be filled with the number of
+ replacements done.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ <function>preg_replace</function> returns an array if the
+ <parameter>subject</parameter> parameter is an array, or a string
+ otherwise.
+ </para>
+ <para>
+ If matches are found, the new <parameter>subject</parameter> will
+ be returned, otherwise <parameter>subject</parameter> will be
+ returned unchanged.
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>4.0.1pl2</entry>
+ <entry>
+ Added the <parameter>limit</parameter> parameter
+ </entry>
+ </row>
+ <row>
+ <entry>4.0.4</entry>
+ <entry>
+ Added the '$n' form for the <parameter>replacement</parameter>
parameter
+ </entry>
+ </row>
+ <row>
+ <entry>5.1.0</entry>
+ <entry>
+ Added the <parameter>count</parameter> parameter
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Convert HTML to text</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// $document should contain an HTML document.
+// This will remove HTML tags, javascript sections
+// and white space. It will also convert some
+// common HTML entities to their text equivalent.
+$search = array ('@<script[^>]*?>.*?</script>@si', // Strip out javascript
+ '@<[\/\!]*?[^<>]*?>@si', // Strip out HTML tags
+ '@([\r\n])[\s]+@', // Strip out white space
+ '@&(quot|#34);@i', // Replace HTML entities
+ '@&(amp|#38);@i',
+ '@&(lt|#60);@i',
+ '@&(gt|#62);@i',
+ '@&(nbsp|#160);@i',
+ '@&(iexcl|#161);@i',
+ '@&(cent|#162);@i',
+ '@&(pound|#163);@i',
+ '@&(copy|#169);@i',
+ '@&#(\d+);@e'); // evaluate as php
+
+$replace = array ('',
+ '',
+ '\1',
+ '"',
+ '&',
+ '<',
+ '>',
+ ' ',
+ chr(161),
+ chr(162),
+ chr(163),
+ chr(169),
+ 'chr(\1)');
+
+$text = preg_replace($search, $replace, $document);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
<example>
<title>Using backreferences followed by numeric literals</title>
<programlisting role="php">
<![CDATA[
<?php
-$string = "April 15, 2003";
-$pattern = "/(\w+) (\d+), (\d+)/i";
-$replacement = "\${1}1,\$3";
+$string = 'April 15, 2003';
+$pattern = '/(\w+) (\d+), (\d+)/i';
+$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>
]]>
</programlisting>
- <para>
- This example will output :
- </para>
+ &example.outputs;
<screen>
<![CDATA[
April1,2003
@@ -71,42 +238,23 @@
</example>
</para>
<para>
- If matches are found, the new <parameter>subject</parameter> will
- be returned, otherwise <parameter>subject</parameter> will be
- returned unchanged.
- </para>
- <para>
- Every parameter to <function>preg_replace</function> (except
- <parameter>limit</parameter>) can be an unidimensional array.
- When using arrays with <parameter>pattern</parameter> and
- <parameter>replacement</parameter>, the keys are processed in the order
- they appear in the array. This is <emphasis>not necessarily</emphasis>
- the same as the numerical index order. If you use indexes to identify
- which <parameter>pattern</parameter> should be replaced by which
- <parameter>replacement</parameter>, you should perform a
- <function>ksort</function> on each array prior to calling
- <function>preg_replace</function>.
- </para>
- <para>
<example>
<title>Using indexed arrays with <function>preg_replace</function></title>
<programlisting role="php">
<![CDATA[
<?php
-$string = "The quick brown fox jumped over the lazy dog.";
-$patterns[0] = "/quick/";
-$patterns[1] = "/brown/";
-$patterns[2] = "/fox/";
-$replacements[2] = "bear";
-$replacements[1] = "black";
-$replacements[0] = "slow";
+$string = 'The quick brown fox jumped over the lazy dog.';
+$patterns[0] = '/quick/';
+$patterns[1] = '/brown/';
+$patterns[2] = '/fox/';
+$replacements[2] = 'bear';
+$replacements[1] = 'black';
+$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>
]]>
</programlisting>
- <para>
- Output:
- </para>
+ &example.outputs;
<screen>
<![CDATA[
The bear black slow jumped over the lazy dog.
@@ -124,9 +272,7 @@
?>
]]>
</programlisting>
- <para>
- Output :
- </para>
+ &example.outputs;
<screen>
<![CDATA[
The slow black bear jumped over the lazy dog.
@@ -135,47 +281,19 @@
</example>
</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>pattern</parameter> and <parameter>replacement</parameter>
- are arrays, then <function>preg_replace</function> takes a value from
- each array and uses them to do search and replace on
- <parameter>subject</parameter>. If <parameter>replacement</parameter>
- has fewer values than <parameter>pattern</parameter>, then empty string
- is used for the rest of replacement values. If <parameter>pattern
- </parameter> is an array and <parameter>replacement</parameter> is a
- string, then this replacement string is used for every value of
- <parameter>pattern</parameter>. The converse would not make sense,
- though.
- </para>
- <para>
- The <literal>e</literal> modifier makes <function>preg_replace</function>
- treat the <parameter>replacement</parameter> parameter as PHP code after
- the appropriate references substitution is done. Tip: make sure that
- <parameter>replacement</parameter> constitutes a valid PHP code string,
- otherwise PHP will complain about a parse error at the line containing
- <function>preg_replace</function>.
- </para>
- <para>
<example>
<title>Replacing several values</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");
+$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>
- <para>
- This example will produce:
- </para>
+ &example.outputs;
<screen>
<![CDATA[
$startDate = 5/27/1999
@@ -190,8 +308,8 @@
<![CDATA[
<?php
preg_replace("/(<\/?)(\w+)([^>]*>)/e",
- "'\\1'.strtoupper('\\2').'\\3'",
- $html_body);
+ "'\\1'.strtoupper('\\2').'\\3'",
+ $html_body);
?>
]]>
</programlisting>
@@ -202,41 +320,17 @@
</para>
<para>
<example>
- <title>Convert HTML to text</title>
+ <title>Strip whitespace</title>
+ <para>
+ This example strips excess whitespace from a string.
+ </para>
<programlisting role="php">
<![CDATA[
<?php
-// $document should contain an HTML document.
-// This will remove HTML tags, javascript sections
-// and white space. It will also convert some
-// common HTML entities to their text equivalent.
-$search = array ("'<script[^>]*?>.*?</script>'si", // Strip out javascript
- "'<[\/\!]*?[^<>]*?>'si", // Strip out HTML tags
- "'([\r\n])[\s]+'", // Strip out white space
- "'&(quot|#34);'i", // Replace HTML entities
- "'&(amp|#38);'i",
- "'&(lt|#60);'i",
- "'&(gt|#62);'i",
- "'&(nbsp|#160);'i",
- "'&(iexcl|#161);'i",
- "'&(cent|#162);'i",
- "'&(pound|#163);'i",
- "'&(copy|#169);'i",
- "'&#(\d+);'e"); // evaluate as php
-$replace = array ("",
- "",
- "\\1",
- "\"",
- "&",
- "<",
- ">",
- " ",
- chr(161),
- chr(162),
- chr(163),
- chr(169),
- "chr(\\1)");
-$text = preg_replace($search, $replace, $document);
+$str = 'foo o';
+$str = preg_replace('/\s\s+/', ' ', $str);
+// This will be 'foo o' now
+echo $str;
?>
]]>
</programlisting>
@@ -244,31 +338,52 @@
</para>
<para>
<example>
- <title>Strip whitespace</title>
- <para>
- This example strips excess whitespace from a string.
- </para>
+ <title>Using the <parameter>count</parameter> parameter</title>
<programlisting role="php">
<![CDATA[
<?php
-$str = 'foo o';
-$str = preg_replace('/\s\s+/', ' ', $str);
-// This will be 'foo o' now
-echo $str;
+$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 <parameter>limit</parameter> was added after PHP 4.0.1pl2.
+ When using arrays with <parameter>pattern</parameter> and
+ <parameter>replacement</parameter>, the keys are processed in the order
+ they appear in the array. This is <emphasis>not necessarily</emphasis> the
+ same as the numerical index order. If you use indexes to identify which
+ <parameter>pattern</parameter> should be replaced by which
+ <parameter>replacement</parameter>, you should perform a
+ <function>ksort</function> on each array prior to calling
+ <function>preg_replace</function>.
</para>
</note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>preg_match</function>,
- <function>preg_match_all</function>, and
- <function>preg_split</function>.
+ <simplelist>
+ <member><function>preg_match</function></member>
+ <member><function>preg_replace_callback</function></member>
+ <member><function>preg_split</function></member>
+ </simplelist>
</para>
</refsect1>
</refentry>
