<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strrpos">
 <refnamediv>
  <refname>strrpos</refname>
  <refpurpose>Find the position of the last occurrence of a substring in a string</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>strrpos</methodname>
   <methodparam><type>string</type><parameter>haystack</parameter></methodparam>
   <methodparam><type>string</type><parameter>needle</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Find the numeric position of the last occurrence of
   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>haystack</parameter></term>
     <listitem>
      <para>
       The string to search in.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>needle</parameter></term>
     <listitem>
      <para>
       If <parameter>needle</parameter> is not a string, it is converted
       to an integer and applied as the ordinal value of a character.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       If specified, search will start this number of characters counted from the
       beginning of the string. If the value is negative, search will instead start
       from that many characters from the end of the string, searching backwards.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the position where the needle exists relative to the beginnning of
   the <parameter>haystack</parameter> string (independent of search direction
   or offset).
   Also note that string positions start at 0, and not 1.
  </para>
  <para>
   Returns &false; if the needle was not found.
  </para>
  &return.falseproblem;
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.0.0</entry>
       <entry>
        The <parameter>needle</parameter> may now be a string of more than one
        character.
       </entry>
      </row>
      <row>
       <entry>5.0.0</entry>
       <entry>
        The <parameter>offset</parameter> parameter was introduced.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Checking if a needle is in the haystack</title>
    <para>
     It is easy to mistake the return values for "character found at
     position 0" and "character not found".  Here's how to detect
     the difference:
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$pos = strrpos($mystring, "b");
if ($pos === false) { // note: three equal signs
    // not found...
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Searching with offsets</title>
    <programlisting role="php">
<![CDATA[
<?php
$foo = "0123456789a123456789b123456789c";

var_dump(strrpos($foo, '7', -5));  // Starts looking backwards five positions
                                   // from the end. Result: int(17)

var_dump(strrpos($foo, '7', 20));  // Starts searching 20 positions into the
                                   // string. Result: int(27)

var_dump(strrpos($foo, '7', 28));  // Result: bool(false)
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>strpos</function></member>
    <member><function>stripos</function></member>
    <member><function>strripos</function></member>
    <member><function>strrchr</function></member>
    <member><function>substr</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- 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:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->