[PHP-DOC] cvs: phpdoc /en/functions regex.xml

[jim winstead]

jimw            Thu Nov  1 21:18:24 2001 EDT

  Modified files:              
    /phpdoc/en/functions        regex.xml 
  Log:
  steer people towards pcre functions. incorporate notes and examples from user notes.
  
Index: phpdoc/en/functions/regex.xml
diff -u phpdoc/en/functions/regex.xml:1.27 phpdoc/en/functions/regex.xml:1.28
--- phpdoc/en/functions/regex.xml:1.27  Fri Sep 21 18:47:46 2001
+++ phpdoc/en/functions/regex.xml       Thu Nov  1 21:18:24 2001
@@ -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 @@
 /* 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 @@
       </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 @@
     </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 @@
       <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 @@
       </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 @@
      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 @@
       </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 @@
      <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 @@
     </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>