in-array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.in-array" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>in_array</refname>
  <refpurpose>Checks if a value exists in an array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>in_array</methodname>
   <methodparam><type>mixed</type><parameter>needle</parameter></methodparam>
   <methodparam><type>array</type><parameter>haystack</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>strict</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Searches for <parameter>needle</parameter> in <parameter>haystack</parameter> using loose comparison
   unless <parameter>strict</parameter> is set.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>needle</parameter></term>
     <listitem>
      <para>
       The searched value.
      </para>
      <note>
       <para>
        If <parameter>needle</parameter> is a string, the comparison is done
        in a case-sensitive manner.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>haystack</parameter></term>
     <listitem>
      <para>
       The array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>strict</parameter></term>
     <listitem>
      <para>
       If the third parameter <parameter>strict</parameter> is set to &true;
       then the <function>in_array</function> function will also check the
       <link linkend="language.types">types</link> of the
       <parameter>needle</parameter> in the <parameter>haystack</parameter>.
      </para>
      <note>
       <para>
        Prior to PHP 8.0.0, a <literal>string</literal> <parameter>needle</parameter> will match an array
        value of <literal>0</literal> in non-strict mode, and vice versa.  That may lead to undesireable
        results.  Similar edge cases exist for other types, as well.  If not absolutely certain of the
        types of values involved, always use the <parameter>strict</parameter> flag to avoid unexpected behavior.
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &true; if <parameter>needle</parameter> is found in the array,
   &false; otherwise.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>in_array</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$os = array("Mac", "NT", "Irix", "Linux");
if (in_array("Irix", $os)) {
    echo "Got Irix";
}
if (in_array("mac", $os)) {
    echo "Got mac";
}
?>
]]>
    </programlisting>
    <para>
     The second condition fails because <function>in_array</function>
     is case-sensitive, so the program above will display:
    </para>
    <screen>
<![CDATA[
Got Irix
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>in_array</function> with strict example</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = array('1.10', 12.4, 1.13);

if (in_array('12.4', $a, true)) {
    echo "'12.4' found with strict check\n";
}

if (in_array(1.13, $a, true)) {
    echo "1.13 found with strict check\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
1.13 found with strict check
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>in_array</function> with an array as needle</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = array(array('p', 'h'), array('p', 'r'), 'o');

if (in_array(array('p', 'h'), $a)) {
    echo "'ph' was found\n";
}

if (in_array(array('f', 'i'), $a)) {
    echo "'fi' was found\n";
}

if (in_array('o', $a)) {
    echo "'o' was found\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
  'ph' was found
  'o' was found
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>array_search</function></member>
    <member><function>isset</function></member>
    <member><function>array_key_exists</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
-->