[PHP-DOC] cvs: phpdoc /it/functions regex.xml From: Luca Perugini (l.perugini <email protected>)
Date: 08/31/00

perugini Thu Aug 31 15:33:25 2000 EDT

  Modified files:
    /phpdoc/it/functions regex.xml
  Log:
  Sync with en tree.
  
  
Index: phpdoc/it/functions/regex.xml
diff -u phpdoc/it/functions/regex.xml:1.2 phpdoc/it/functions/regex.xml:1.3
--- phpdoc/it/functions/regex.xml:1.2 Sat Jun 24 00:38:44 2000
+++ phpdoc/it/functions/regex.xml Thu Aug 31 15:33:25 2000
@@ -1,11 +1,11 @@
  <reference id="ref.regex">
- <title>Regular expression functions</title>
+ <title>Regular Expression Functions (POSIX Extended)</title>
   <titleabbrev>Regexps</titleabbrev>
+
   <partintro>
    <para>
     Regular expressions are used for complex string manipulation in
     PHP. The functions that support regular expressions are:
-
     <itemizedlist>
      <listitem>
       <simpara><function>ereg</function></simpara>
@@ -22,8 +22,10 @@
      <listitem>
       <simpara><function>split</function></simpara>
      </listitem>
+ <listitem>
+ <simpara><function>spliti</function></simpara>
+ </listitem>
     </itemizedlist>
-
     These functions all take a regular expression string as their
     first argument. PHP uses the POSIX extended regular expressions
     as defined by POSIX 1003.2. For a full description of POSIX
@@ -32,51 +34,51 @@
     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>
+ <!-- Should add discussion of PCRE functions here. -->
 
+ </para>
    <para>
     <example>
- <title>Regular expression examples</title>
- <programlisting>
-ereg(&quot;abc&quot;,$string);
+ <title>Regular Expression Examples</title>
+ <programlisting role="php">
+ereg (&quot;abc&quot;, $string);
 /* Returns true if &quot;abc&quot;
    is found anywhere in $string. */
 
-ereg(&quot;^abc&quot;,$string);
+ereg (&quot;^abc&quot;, $string);
 /* Returns true if &quot;abc&quot;
    is found at the beginning of $string. */
 
-ereg("abc$",$string);
+ereg ("abc$", $string);
 /* Returns true if &quot;abc&quot;
    is found at the end of $string. */
 
-eregi("(ozilla.[23]|MSIE.3)",$HTTP_USER_AGENT);
+eregi ("(ozilla.[23]|MSIE.3)", $HTTP_USER_AGENT);
 /* Returns true if client browser
    is Netscape 2, 3 or MSIE 3. */
 
-ereg("([[:alnum:]]+) ([[:alnum:]]+) ([[:alnum:]]+)",
- $string,$regs);
+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);
+$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);
+$string = ereg_replace ("$", "&lt;BR&gt;", $string);
 /* Put a &lt;BR&gt; tag at the end of $string. */
 
-$string = ereg_replace("\n","",$string);
+$string = ereg_replace ("\n", "", $string);
 /* Get rid of any newline
    characters in $string. */
      </programlisting>
- </example></para>
-
+ </example>
+ </para>
   </partintro>
 
   <refentry id="function.ereg">
    <refnamediv>
     <refname>ereg</refname>
- <refpurpose>regular expression match</refpurpose>
+ <refpurpose>Regular expression match</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -85,54 +87,67 @@
       <funcdef>int <function>ereg</function></funcdef>
       <paramdef>string <parameter>pattern</parameter></paramdef>
       <paramdef>string <parameter>string</parameter></paramdef>
- <paramdef>array <parameter><optional>regs</optional></parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>regs</optional></parameter>
+ </paramdef>
      </funcprototype>
     </funcsynopsis>
     <simpara>
- Searchs <parameter>string</parameter> for matches to the regular expression
- given in <parameter>pattern</parameter>.</simpara>
-
+ Searches a <parameter>string</parameter> for matches to the regular
+ expression given in <parameter>pattern</parameter>.
+ </simpara>
     <simpara>
      If matches are found for parenthesized substrings of
      <parameter>pattern</parameter> and the function is called with
      the third argument <parameter>regs</parameter>, the matches will
- be stored in the elements of
+ be stored in the elements of the array
      <parameter>regs</parameter>. $regs[1] will contain the substring
- which starts at the first left parenthesis; $regs[2] will contain the
- substring starting at the second, and so on. $regs[0] will
- contain a copy of <parameter>string</parameter>.</simpara>
-
- <para>
- Searching is case sensitive.</para>
-
- <para>
- Returns true if a match for pattern was found in string, or false
- if no matches were found or an error occurred.</para>
-
+ which starts at the first left parenthesis; $regs[2] will contain
+ the substring starting at the second, and so on. $regs[0] will
+ contain a copy of <parameter>string</parameter>.
+ </simpara>
+ <simpara>
+ If <function>ereg</function> finds any matches at all, $regs will
+ be filled with exactly ten elements, even though more or fewer
+ than ten parenthesized substrings may actually have matched.
+ This has no effect on <function>ereg</function>'s ability to
+ match more substrings. If no matches are found, $regs will not be
+ altered by <function>ereg</function>.
+ </simpara>
+ <simpara>
+ Searching is case sensitive.
+ </simpara>
+ <simpara>
+ Returns true if a match for <parameter>pattern</parameter> was
+ found in <parameter>string</parameter>, or false if no matches
+ were found or an error occurred.
+ </simpara>
     <para>
- The following code snippet takes a date in ISO format (YYYY-MM-DD)
- and prints it in DD.MM.YYYY format:
+ The following code snippet takes a date in ISO format
+ (YYYY-MM-DD) and prints it in DD.MM.YYYY format:
      <example>
- <title>ereg() example</title>
- <programlisting>
-if ( ereg( "([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs ) ) {
+ <title><function>Ereg</function> Example</title>
+ <programlisting role="php">
+if (ereg ("([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs)) {
     echo "$regs[3].$regs[2].$regs[1]";
 } else {
     echo "Invalid date format: $date";
 }
-</programlisting></example></para>
-
- <para>
- See also <function>eregi</function>, <function>ereg_replace</function>, and <function>eregi_replace</function>.</para>
-
+ </programlisting>
+ </example>
+ </para>
+ <simpara>
+ See also <function>eregi</function>,
+ <function>ereg_replace</function>, and
+ <function>eregi_replace</function>.
+ </simpara>
    </refsect1>
   </refentry>
 
-
   <refentry id="function.ereg-replace">
    <refnamediv>
     <refname>ereg_replace</refname>
- <refpurpose>replace regular expression</refpurpose>
+ <refpurpose>Replace regular expression</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -144,17 +159,17 @@
       <paramdef>string <parameter>string</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
- <para>
+ <simpara>
      This function scans <parameter>string</parameter> for matches to
      <parameter>pattern</parameter>, then replaces the matched text
- with <parameter>replacement</parameter>.</para>
-
- <para>
+ with <parameter>replacement</parameter>.
+ </simpara>
+ <simpara>
      The modified string is returned. (Which may mean that the
      original string is returned if there are no matches to be
- replaced.)</para>
-
- <para>
+ replaced.)
+ </simpara>
+ <simpara>
      If <parameter>pattern</parameter> contains parenthesized
      substrings, <parameter>replacement</parameter> may contain
      substrings of the form
@@ -163,32 +178,57 @@
      substring; <literal>\\0</literal> will produce the entire
      contents of string. Up to nine substrings may be used.
      Parentheses may be nested, in which case they are counted by the
- opening parenthesis.</para>
-
- <para>
+ opening parenthesis.
+ </simpara>
+ <simpara>
      If no matches are found in <parameter>string</parameter>, then
- <parameter>string</parameter> will be returned unchanged.</para>
-
+ <parameter>string</parameter> will be returned unchanged.
+ </simpara>
     <para>
- For example, the following code snippet
- prints "This was a test" three times:
+ For example, the following code snippet prints "This was a test"
+ three times:
      <example>
- <title>ereg_replace() example</title>
+ <title><function>Ereg_replace</function> Example</title>
       <programlisting>
 $string = "This is a test";
-echo ereg_replace( " is", " was", $string );
-echo ereg_replace( "( )is", "\\1was", $string );
-echo ereg_replace( "(( )is)", "\\2was", $string );
+echo ereg_replace (" is", " was", $string);
+echo ereg_replace ("( )is", "\\1was", $string);
+echo ereg_replace ("(( )is)", "\\2was", $string);
       </programlisting>
- </example></para>
-
+ </example>
+ </para>
     <para>
+ One thing to take note of is that if you use an integer value as
+ the <parameter>replacement</parameter> parameter, you may not get
+ the results you expect. This is because
+ <function>ereg_replace</function> will interpret the number as
+ the ordinal value of a character, and apply that. For instance:
+ <example>
+ <title><function>ereg_replace</function> Example</title>
+ <programlisting>
+&lt;?php
+/* This will not work as expected. */
+$num = 4;
+$string = "This string has four words.";
+$string = ereg_replace('four', $num, $string);
+echo $string; /* Output: 'This string has words.' */
+
+/* This will work. */
+$num = '4';
+$string = "This string has four words.";
+$string = ereg_replace('four', $num, $string);
+echo $string; /* Output: 'This string has 4 words.' */
+?>
+ </programlisting>
+ </example>
+ </para>
+ <simpara>
      See also <function>ereg</function>, <function>eregi</function>,
- and <function>eregi_replace</function>.</para>
+ and <function>eregi_replace</function>.
+ </simpara>
    </refsect1>
   </refentry>
 
-
   <refentry id="function.eregi">
    <refnamediv>
     <refname>eregi</refname>
@@ -201,20 +241,24 @@
       <funcdef>int <function>eregi</function></funcdef>
       <paramdef>string <parameter>pattern</parameter></paramdef>
       <paramdef>string <parameter>string</parameter></paramdef>
- <paramdef>array <parameter><optional>regs</optional></parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>regs</optional></parameter>
+ </paramdef>
      </funcprototype>
     </funcsynopsis>
- <para>
- This function is identical to <function>ereg</function> save that this ignores
- case distinction when matching alphabetic characters.</para>
-
     <para>
- See also <function>ereg</function>, <function>ereg_replace</function>, and <function>eregi_replace</function>.</para>
-
+ This function is identical to <function>ereg</function> except
+ that this ignores case distinction when matching alphabetic
+ characters.
+ </para>
+ <para>
+ See also <function>ereg</function>,
+ <function>ereg_replace</function>, and
+ <function>eregi_replace</function>.
+ </para>
    </refsect1>
   </refentry>
 
-
   <refentry id="function.eregi-replace">
    <refnamediv>
     <refname>eregi_replace</refname>
@@ -231,16 +275,17 @@
      </funcprototype>
     </funcsynopsis>
     <para>
- This function is identical to <function>ereg_replace</function> save that
- this ignores case distinction when matching alphabetic characters.</para>
-
+ This function is identical to <function>ereg_replace</function>
+ except that this ignores case distinction when matching
+ alphabetic characters.
+ </para>
     <para>
- See also <function>ereg</function>, <function>eregi</function>, and <function>ereg_replace</function>.</para>
-
+ See also <function>ereg</function>, <function>eregi</function>,
+ and <function>ereg_replace</function>.
+ </para>
    </refsect1>
   </refentry>
 
-
   <refentry id="function.split">
    <refnamediv>
     <refname>split</refname>
@@ -253,75 +298,107 @@
       <funcdef>array <function>split</function></funcdef>
       <paramdef>string <parameter>pattern</parameter></paramdef>
       <paramdef>string <parameter>string</parameter></paramdef>
- <paramdef>int <parameter><optional>limit</optional></parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>limit</optional></parameter>
+ </paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      Returns an array of strings, each of which is a substring of
- string formed by splitting it on boundaries formed by the regular
- expression <parameter>pattern</parameter>. If an error occurs,
- returns false.
- </para>
-
+ <parameter>string</parameter> formed by splitting it on
+ boundaries formed by the regular expression
+ <parameter>pattern</parameter>. If <parameter>limit</parameter>
+ is set, the returned array will contain a maximum of
+ <parameter>limit</parameter> elements with the last element
+ containing the whole rest of <parameter>string</parameter>. If
+ an error occurs, <function>split</function> returns false.
+ </para>
     <para>
      To get the first five fields from a line from
      <filename>/etc/passwd</filename>:
- <example>
- <title>split() example</title>
- <programlisting>
-$passwd_list = split( ":", $passwd_line, 5 );
- </programlisting>
- </example>
- </para>
-
+ <example>
+ <title><function>Split</function> Example</title>
+ <programlisting role="php">
+$passwd_list = split (":", $passwd_line, 5);
+ </programlisting>
+ </example>
+ </para>
     <para>
- To parse a date which may be delimited with slashes, dots, or
- hyphens:
- <example>
- <title>split() example</title>
- <programlisting>
+ To parse a date which may be delimited with slashes, dots, or
+ hyphens:
+ <example>
+ <title><function>Split</function> Example</title>
+ <programlisting role="php">
 $date = "04/30/1973"; // Delimiters may be slash, dot, or hyphen
-list( $month, $day, $year ) = split( '[/.-]', $date );
+list ($month, $day, $year) = split ('[/.-]', $date);
 echo "Month: $month; Day: $day; Year: $year&lt;br&gt;\n";
- </programlisting>
- </example>
- </para>
-
+ </programlisting>
+ </example>
+ </para>
     <para>
      Note that <parameter>pattern</parameter> is case-sensitive.
- </para>
-
- <para>
- Note that if you don't require the power of regular expressions,
- it is faster to use <function>explode</function>, which doesn't
- incur the overhead of the regular expression engine.
- </para>
-
- <para>
- Please note that <parameter>pattern</parameter> is a regular
- expression. If you want to split on any of the characters which
- are considered special by regular expressions, you'll need to
- escape them first. If you think <function>split</function> (or
- any other regex function, for that matter) is doing something
- weird, please read the file <filename>regex.7</filename>,
- included in the <filename>regex/</filename> subdirectory of 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.
- </para>
-
+ </para>
     <para>
- See also: <function>explode</function> and <function>implode</function>.
- </para>
-
+ Note that if you don't require the power of regular expressions,
+ it is faster to use <function>explode</function>, which doesn't
+ incur the overhead of the regular expression engine.
+ </para>
+ <para>
+ Please note that <parameter>pattern</parameter> is a regular
+ expression. If you want to split on any of the characters which
+ are considered special by regular expressions, you'll need to
+ escape them first. If you think <function>split</function> (or
+ any other regex function, for that matter) is doing something
+ weird, please read the file <filename>regex.7</filename>,
+ included in the <filename>regex/</filename> subdirectory of 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.
+ </para>
+ <para>
+ See also: <function>spliti</function>,
+ <function>explode</function>, and <function>implode</function>.
+ </para>
    </refsect1>
   </refentry>
-
+
+ <refentry id="function.spliti">
+ <refnamediv>
+ <refname>spliti</refname>
+ <refpurpose>
+ Split string into array by regular expression case insensitive
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>split</function></funcdef>
+ <paramdef>string <parameter>pattern</parameter></paramdef>
+ <paramdef>string <parameter>string</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>limit</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function is identical to <function>split</function> except
+ that this ignores case distinction when matching alphabetic
+ characters.
+ </para>
+ <para>
+ See also: <function>split</function>,
+ <function>explode</function>, and <function>implode</function>.
+ </para>
+ </refsect1>
+ </refentry>
 
   <refentry id="function.sql-regcase">
    <refnamediv>
     <refname>sql_regcase</refname>
- <refpurpose>make regular expression for case insensitive match</refpurpose>
+ <refpurpose>
+ Make regular expression for case insensitive match
+ </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -332,24 +409,24 @@
      </funcprototype>
     </funcsynopsis>
     <para>
- Returns a valid regular expression which will match <parameter>string</parameter>,
- ignoring case. This expression is <parameter>string</parameter> with each character
- converted to a bracket expression; this bracket expression
- contains that character's uppercase and lowercase form if
- applicable, otherwise it contains the original character
- twice.
+ Returns a valid regular expression which will match
+ <parameter>string</parameter>, ignoring case. This expression is
+ <parameter>string</parameter> with each character converted to a
+ bracket expression; this bracket expression contains that
+ character's uppercase and lowercase form if applicable, otherwise
+ it contains the original character twice.
      <example>
- <title>sql_regcase() example</title>
- <programlisting>
-echo sql_regcase( "Foo bar" );
-</programlisting></example>
-
- prints <screen>[Ff][Oo][Oo][ ][Bb][Aa][Rr]</screen>.</para>
-
+ <title><function>Sql_regcase</function> Example</title>
+ <programlisting role="php">
+echo sql_regcase ("Foo bar");
+ </programlisting>
+ </example>
+ prints <screen>[Ff][Oo][Oo][ ][Bb][Aa][Rr]</screen>.
+ </para>
     <para>
      This can be used to achieve case insensitive pattern matching in
- products which support only case sensitive regular expressions.</para>
-
+ products which support only case sensitive regular expressions.
+ </para>
    </refsect1>
   </refentry>
 
@@ -366,7 +443,7 @@
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document:nil
-sgml-default-dtd-file:"../manual.ced"
+sgml-default-dtd-file:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil