archived-doc-en/reference/strings/functions/stripos.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.stripos" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stripos</refname>
  <refpurpose>Find the position of the first occurrence of a case-insensitive substring in a string</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>stripos</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 first occurrence of
   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
  </para>
  <para>
   Unlike the <function>strpos</function>, <function>stripos</function> is
   case-insensitive.
  </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>
       The string to search for.
      </para>
      &strings.parameter.needle.non-string;
     </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 offset is negative, the search will start
       this number of characters counted from the end of the string.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the position of where the needle exists relative to the beginning of
   the <parameter>haystack</parameter> string (independent of 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="errors">
  &reftitle.errors;
  <itemizedlist>
   <listitem>
    <simpara>
     If <parameter>offset</parameter> is greater than the length of
     <parameter>haystack</parameter>, a
     <classname>ValueError</classname> will be thrown.
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &strings.changelog.ascii-case-folding;
     &strings.changelog.needle-empty;
     <row>
      <entry>8.0.0</entry>
      <entry>
       Passing an &integer; as <parameter>needle</parameter> is no longer supported.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Passing an &integer; as <parameter>needle</parameter> has been deprecated.
      </entry>
     </row>
     <row>
      <entry>7.1.0</entry>
      <entry>
       Support for negative <parameter>offset</parameter>s has been added.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
   <title><function>stripos</function> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
$findme    = 'a';
$mystring1 = 'xyz';
$mystring2 = 'ABC';

$pos1 = stripos($mystring1, $findme);
$pos2 = stripos($mystring2, $findme);

// Nope, 'a' is certainly not in 'xyz'
if ($pos1 === false) {
    echo "The string '$findme' was not found in the string '$mystring1'", PHP_EOL;
}

// Note our use of !==.  Simply != would not work as expected
// because the position of 'a' is the 0th (first) character.
if ($pos2 !== false) {
    echo "We found '$findme' in '$mystring2' at position $pos2", PHP_EOL;
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mb_stripos</function></member>
    <member><function>str_contains</function></member>
    <member><function>str_ends_with</function></member>
    <member><function>str_starts_with</function></member>
    <member><function>strpos</function></member>
    <member><function>strrpos</function></member>
    <member><function>strripos</function></member>
    <member><function>stristr</function></member>
    <member><function>substr</function></member>
    <member><function>str_ireplace</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
-->