cvs: phpdoc /en/reference/var/functions empty.xml

philip Wed May 21 16:42:06 2003 EDT Modified files: /phpdoc/en/reference/var/functions empty.xml Log: Update docs to be more informative on what's considered empty. And a few more see also's. Index: phpdoc/en/reference/var/functions/empty.xml diff -u phpdoc/en/reference/var/functions/empty.xml:1.4 phpdoc/en/reference/var/functions/empty.xml:1.5 --- phpdoc/en/reference/var/functions/empty.xml:1.4 Sun May 4 13:13:07 2003 +++ phpdoc/en/reference/var/functions/empty.xml Wed May 21 16:42:06 2003 @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <!-- splitted from ./en/functions/var.xml, last change in rev 1.2 --> <refentry id="function.empty"> <refnamediv> <refname>empty</refname> - <refpurpose>Determine whether a variable is set</refpurpose> + <refpurpose>Determine whether a variable is empty</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -12,49 +12,63 @@ <type>bool</type><methodname>empty</methodname> <methodparam><type>mixed</type><parameter>var</parameter></methodparam> </methodsynopsis> - <note> - <para> - <function>empty</function> is a language construct. - </para> - </note> - &note.language-construct; <para> - This is the opposite of + <function>empty</function> returns &false; if + <parameter>var</parameter> has a non-empty or non-zero value. In + otherwords, <literal>""</literal>, <literal>0</literal>, + <literal>"0"</literal>, &null;, &false;, <literal>array()</literal>, + <literal>var $var;</literal>, and objects with empty properties, are + all considered empty. &true; is returned if <parameter>var</parameter> + is not empty. + </para> + <para> + <function>empty</function> is the opposite of <literal>(boolean) <parameter>var</parameter></literal>, except that no warning is generated when the variable is not set. See <link linkend="language.types.boolean.casting">converting to boolean</link> for more information. </para> - - <!-- Returns &false; if <parameter>var</parameter> is set and has a - non-empty or non-zero value; &true; otherwise. --> - - <informalexample> + <para> + <example> + <title> + A simple <function>empty</function> / <function>isset</function> + comparison. + </title> <programlisting role="php"> <![CDATA[ +<?php $var = 0; -if (empty($var)) { // evaluates true - echo '$var is either 0 or not set at all'; +// Evaluates to true because $var is empty +if (empty($var)) { + echo '$var is either 0, empty, or not set at all'; } -if (!isset($var)) { // evaluates false - echo '$var is not set at all'; +// Evaluates as true because $var is set +if (isset($var)) { + echo '$var is set even though it is empty'; } +?> ]]> </programlisting> - </informalexample> + </example> + </para> + &note.language-construct; + + <note> + <para> + <function>empty</function> only checks variables as anything else will + result in a parse error. In otherwords, the following will not work: + <command>empty(addslashes($name))</command>. + </para> + </note> <simpara> - Note that this is meaningless when used on anything which isn't a - variable; i.e. <command>empty (addslashes ($name))</command> has - no meaning since it would be checking whether something which - isn't a variable is a variable with a &false; value. - <!-- will even result in parse error (at least in PHP 4) --> - </simpara> - <simpara> - See also <function>isset</function> and - <function>unset</function>. + See also <function>isset</function>, + <function>unset</function>, + <function>array_key_exists</function>, + <function>count</function>, and + <function>strlen</function>. </simpara> </refsect1> </refentry>