steer people towards pcre functions. incorporate notes and examples from user notes.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@61382 c90b9560-bf6c-de11-be94-00142212c4b1

functions/regex.xml

@@ -1,10 +1,25 @@
 <?xml encoding="iso-8859-1"?>
-<!-- $Revision: 1.27 $ -->
+<!-- $Revision: 1.28 $ -->
  <reference id="ref.regex">
   <title>Regular Expression Functions (POSIX Extended)</title>
   <titleabbrev>Regexps</titleabbrev>
 
   <partintro>
+   <note>
+    <para>
+     PHP also supports regular expressions using a Perl-compatible syntax
+     using the <link linkend="ref.pcre">PCRE functions</link>. Those functions
+     support non-greedy matching, assertions, conditional subpatterns, and a
+     number of other features not supported by the POSIX-extended regular
+     expression syntax.
+    </para>
+   </note>
+   <warning>
+    <para>
+     These regular expression functions are not binary-safe. The <link
+      linkend="ref.pcre">PCRE functions</link> are.
+    </para>
+   </warning>
    <para>
     Regular expressions are used for complex string manipulation in
     PHP. The functions that support regular expressions are:
@@ -35,9 +50,6 @@
     directory in the PHP distribution. It's in manpage format, so
     you'll want to do something along the lines of <command>man
     /usr/local/src/regex/regex.7</command> in order to read it.
-
-    <!-- Should add discussion of PCRE functions here. -->
-
    </para>
    <para>
     <example>
@@ -63,11 +75,11 @@ ereg ("([[:alnum:]]+) ([[:alnum:]]+) ([[:alnum:]]+)", $string,$regs);
 /* Places three space separated words
    into $regs[1], $regs[2] and $regs[3]. */
 
-$string = ereg_replace ("^", "&lt;BR&gt;", $string); 
-/* Put a &lt;BR&gt; tag at the beginning of $string. */
+$string = ereg_replace ("^", "&lt;br /&gt;", $string); 
+/* Put a &lt;br /&gt; tag at the beginning of $string. */
  
-$string = ereg_replace ("$", "&lt;BR&gt;", $string); 
-/* Put a &lt;BR&gt; tag at the end of $string. */
+$string = ereg_replace ("$", "&lt;br /&gt;", $string); 
+/* Put a &lt;br /&gt; tag at the end of $string. */
 
 $string = ereg_replace ("\n", "", $string);
 /* Get rid of any newline
@@ -94,6 +106,13 @@ $string = ereg_replace ("\n", "", $string);
       </paramdef>
      </funcprototype>
     </funcsynopsis>
+    <note>
+     <para>
+      <function>preg_match</function>, which uses a Perl-compatible 
+      regular expression syntax, is often a faster alternative to
+      <function>ereg</function>.
+     </para>
+    </note>
     <simpara>
      Searches a <parameter>string</parameter> for matches to the regular
      expression given in <parameter>pattern</parameter>.
@@ -140,8 +159,9 @@ if (ereg ("([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs)) {
     </para>
     <simpara>
      See also <function>eregi</function>,
-     <function>ereg_replace</function>, and
-     <function>eregi_replace</function>.
+     <function>ereg_replace</function>,
+     <function>eregi_replace</function> and
+     <function>preg_match</function>.
     </simpara>
    </refsect1>
   </refentry>
@@ -161,6 +181,13 @@ if (ereg ("([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs)) {
       <paramdef>string <parameter>string</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
+    <note>
+     <para>
+      <function>preg_replace</function>, which uses a Perl-compatible 
+      regular expression syntax, is often a faster alternative to
+      <function>ereg_replace</function>.
+     </para>
+    </note>
     <simpara>
      This function scans <parameter>string</parameter> for matches to
      <parameter>pattern</parameter>, then replaces the matched text
@@ -224,9 +251,18 @@ echo $string;   /* Output: 'This string has 4 words.' */
       </programlisting>
      </example>
     </para>
+    <para>
+     <example>
+      <title>Replace URLs with links</title>
+      <programlisting role="php">
+$text = ereg_replace("[[:alpha:]]+://[^<>[:space:]]+[[:alnum:]/]",
+                     "&lt;a href=\"\\0\"&gt;\\0&lt;/a&gt;", $text);
+      </programlisting>
+     </example>
+    </para>
     <simpara>
      See also <function>ereg</function>, <function>eregi</function>,
-     and <function>eregi_replace</function>.
+     <function>eregi_replace</function>, and <function>preg_match</function>.
     </simpara>
    </refsect1>
   </refentry>
@@ -252,6 +288,14 @@ echo $string;   /* Output: 'This string has 4 words.' */
      This function is identical to <function>ereg</function> except
      that this ignores case distinction when matching alphabetic
      characters.
+     <example>
+      <title><function>eregi</function> example</title>
+      <programlisting role="php">
+if (eregi("z", $string)) {
+    echo "'$string' contains a 'z' or 'Z'!";
+}
+      </programlisting>
+     </example>
     </para>
     <para>
      See also <function>ereg</function>,
@@ -305,6 +349,13 @@ echo $string;   /* Output: 'This string has 4 words.' */
       </paramdef>
      </funcprototype>
     </funcsynopsis>
+    <note>
+     <para>
+      <function>preg_split</function>, which uses a Perl-compatible 
+      regular expression syntax, is often a faster alternative to
+      <function>split</function>.
+     </para>
+    </note>
     <para>
      Returns an array of strings, each of which is a substring of
      <parameter>string</parameter> formed by splitting it on
@@ -321,7 +372,7 @@ echo $string;   /* Output: 'This string has 4 words.' */
      <example>
       <title><function>split</function> Example</title>
       <programlisting role="php">
-$passwd_list = split (":", $passwd_line, 5);
+list($user,$pass,$uid,$gid,$extra)= split (":", $passwd_line, 5);
       </programlisting>
      </example>
     </para>
@@ -359,7 +410,7 @@ echo "Month: $month; Day: $day; Year: $year&lt;br&gt;\n";
     </para>
 
     <para>
-     For users looking for a way to emulate perl's <command>$chars =
+     For users looking for a way to emulate Perl's <command>$chars =
       split('', $str)</command> behaviour, please see the examples for
      <function>preg_split</function>.
     </para>