<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.regex">
  <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>
     </listitem>
     <listitem>
      <simpara><function>ereg_replace</function></simpara>
     </listitem>
     <listitem>
      <simpara><function>eregi</function></simpara>
     </listitem>
     <listitem>
      <simpara><function>eregi_replace</function></simpara>
     </listitem>
     <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
    regular expressions see the regex man pages included in the regex
    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>
     <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);
/* Returns true if &quot;abc&quot;
   is found at the beginning of $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);  
/* Returns true if client browser
   is Netscape 2, 3 or MSIE 3. */

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 end of $string. */

$string = ereg_replace ("\n", "", $string);
/* Get rid of any newline
   characters in $string. */
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.ereg">
   <refnamediv>
    <refname>ereg</refname>
    <refpurpose>Regular expression match</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ereg</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>regs</parameter></methodparam>
     </methodsynopsis>
    <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 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>
    <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:
     <example>
      <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>
    <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>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ereg_replace</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>replacement</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     This function scans <parameter>string</parameter> for matches to
     <parameter>pattern</parameter>, then replaces the matched text
     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.)
    </simpara>
    <simpara>
     If <parameter>pattern</parameter> contains parenthesized
     substrings, <parameter>replacement</parameter> may contain
     substrings of the form
     <literal>\\<replaceable>digit</replaceable></literal>, which will
     be replaced by the text matching the digit'th parenthesized
     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.
    </simpara>  
    <simpara>
     If no matches are found in <parameter>string</parameter>, then
     <parameter>string</parameter> will be returned unchanged.
    </simpara>
    <para>
     For example, the following code snippet prints "This was a test"
     three times:
     <example>
      <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);
      </programlisting>
     </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>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.eregi">
   <refnamediv>
    <refname>eregi</refname>
    <refpurpose>case insensitive regular expression match</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>eregi</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>regs</parameter></methodparam>
     </methodsynopsis>
    <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>
    <refpurpose>replace regular expression case insensitive</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>eregi_replace</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>replacement</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
     </methodsynopsis>
    <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>
   </refsect1>
  </refentry>

  <refentry id="function.split">
   <refnamediv>
    <refname>split</refname>
    <refpurpose>split string into array by regular expression</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>split</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an array of strings, each of which is a substring of
     <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 split off the first four fields from a line from
     <filename>/etc/passwd</filename>:
     <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><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);
echo "Month: $month; Day: $day; Year: $year&lt;br&gt;\n";
      </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>
     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>

    <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>
     <methodsynopsis>
      <type>array</type><methodname>split</methodname>
      <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>limit</parameter></methodparam>
     </methodsynopsis>
    <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>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>sql_regcase</methodname>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
     </methodsynopsis>
    <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.
     <example>
      <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>
   </refsect1>
  </refentry>


 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->