archived-doc-en/language/types/boolean.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.types.boolean">
 <title>Booleans</title>

 <simpara>
  The <type>bool</type> type only has two values, and is used to express
  a truth value. It can be either &true; or &false;.
 </simpara>

 <sect2 xml:id="language.types.boolean.syntax">
  <title>Syntax</title>
  <para>
   To specify a <type>bool</type> literal, use the constants &true; or
   &false;. Both are case-insensitive.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$foo = True; // assign the value TRUE to $foo
?>
]]>
   </programlisting>
  </informalexample>

  <para>
   Typically, the result of an <link linkend="language.operators">operator</link>
   which returns a <type>bool</type> value is passed on to a
   <link linkend="language.control-structures">control structure</link>.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$action = "show_version";
$show_separators = true;

// == is an operator which tests
// equality and returns a boolean
if ($action == "show_version") {
    echo "The version is 1.23";
}

// this is not necessary...
if ($show_separators == TRUE) {
    echo "<hr>\n";
}

// ...because this can be used with exactly the same meaning:
if ($show_separators) {
    echo "<hr>\n";
}
?>
]]>
   </programlisting>
  </informalexample>
 </sect2>

 <sect2 xml:id="language.types.boolean.casting">
  <title>Converting to boolean</title>

  <simpara>
   To explicitly convert a value to <type>bool</type>, use the
   <literal>(bool)</literal> cast. Generally this is not necessary because when
   a value is used in a logical context it will be automatically interpreted
   as a value of type <type>bool</type>. For more information see the
   <link linkend="language.types.type-juggling">Type Juggling</link> page.
  </simpara>

  <para>
   When converting to <type>bool</type>, the following values are considered
   &false;:
  </para>

  <itemizedlist>
   <listitem>
    <simpara>
     the <link linkend="language.types.boolean">boolean</link> &false; itself
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     the <link linkend="language.types.integer">integer</link>
     <literal>0</literal> (zero)
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     the <link linkend="language.types.float">float</link>s
     <literal>0.0</literal> and <literal>-0.0</literal> (zero)
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     the empty <link linkend="language.types.string">string</link> <literal>""</literal>,
     and the <link linkend="language.types.string">string</link> <literal>"0"</literal>
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     an <link linkend="language.types.array">array</link> with zero elements
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     the unit type <link linkend="language.types.null">NULL</link> (including
     unset variables)
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Internal objects that overload their casting behaviour to bool.
     For example: <link linkend="ref.simplexml">SimpleXML</link> objects
     created from empty elements without attributes.
    </simpara>
   </listitem>
  </itemizedlist>

  <para>
   Every other value is considered &true;
   (including <link linkend="language.types.resource">resource</link>
   and <constant>NAN</constant>).
  </para>

  <warning>
   <simpara>
    <literal>-1</literal> is considered &true;, like any other non-zero
    (whether negative or positive) number!
   </simpara>
  </warning>

  <example>
   <title>Casting to Boolean</title>
   <programlisting role="php">
<![CDATA[
<?php
var_dump((bool) "");        // bool(false)
var_dump((bool) "0");       // bool(false)
var_dump((bool) 1);         // bool(true)
var_dump((bool) -2);        // bool(true)
var_dump((bool) "foo");     // bool(true)
var_dump((bool) 2.3e5);     // bool(true)
var_dump((bool) array(12)); // bool(true)
var_dump((bool) array());   // bool(false)
var_dump((bool) "false");   // bool(true)
?>
]]>
   </programlisting>
  </example>

 </sect2>
</sect1>
<!-- 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
-->