cvs: phpdoc /en/reference/pcre/functions preg-replace.xml

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>