<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.73 $ -->
 <chapter id="language.types">
  <title>Types</title>

  <sect1 id="language.types.intro">
  <title>Introduction</title>
  
  <simpara>
   PHP supports eight primitive <!-- (all types are primitive in php) -->
   types.
  </simpara>
  
  <para>
   Four scalar <!-- (basic, can't be split into parts) --> types:

   <itemizedlist>

    <listitem>
     <simpara>
      <link linkend="language.types.boolean">boolean</link>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <link linkend="language.types.integer">integer</link>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <link linkend="language.types.float">floating-point number (float)</link>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <link linkend="language.types.string">string</link>
     </simpara>
    </listitem>

   </itemizedlist>

   Two compound types:

   <itemizedlist>

    <listitem>
     <simpara>
      <link linkend="language.types.array">array</link>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <link linkend="language.types.object">object</link>
     </simpara>
    </listitem>

   </itemizedlist>

   And finally two special types:

   <itemizedlist>

    <listitem>
     <simpara>
      <link linkend="language.types.resource">resource</link>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <link linkend="language.types.null">NULL</link>
     </simpara>
    </listitem>

   </itemizedlist>
  </para>
  
  <note>
   <simpara>
    In this manual you'll often find <literal>mixed</literal> parameters. 
    This pseudo-type
    indicates multiple possiblities for that parameter.
   </simpara>
   <!--
   
   Just an idea, maybe useful for some func-defs?
   (at least it is for the operator-defs)
   
   <simpara>
    In parameter definitions you can also encounter the 'number' pseudo-type,
    that indicates a parameter that is either <type>integer</type> or 
    <type>float</type>.
   </simpara>
   -->
  </note>


  <simpara>
   The type of a variable is usually not set by the programmer;
   rather, it is decided at runtime by PHP depending on the context in
   which that variable is used.
  </simpara>
  <note>
   <simpara>
    If you want to check out the type and value of a certain <link
     linkend="language.expressions">expression</link>, use
    <function>var_dump</function>.
   </simpara>
   <simpara>
    If you simply want a human-readable representation of the type for
    debugging, use <function>gettype</function>. To check for a certain type,
    do <emphasis>not</emphasis> use <function>gettype</function>, but use the
    <literal>is_<replaceable>type</replaceable></literal> functions.
   </simpara>
   <!-- TODO: example(s) would be great -->
  </note>
  <simpara>
   If you would like to force a variable to be converted to a certain
   type, you may either <link
   linkend="language.types.typecasting">cast</link> the variable or
   use the <function>settype</function> function on it.
  </simpara>
  <simpara>
   Note that a variable may behave in different manners in certain
   situations, depending on what type it is at the time. For more
   information, see the section on <link
   linkend="language.types.type-juggling">Type Juggling</link>.
  </simpara>
  
   
   </sect1>
   
   <sect1 id="language.types.boolean">
    <title>Booleans</title>
    
    <simpara>
     This is the easiest type. A <type>boolean</type> expresses a 
     truth value. It can be either &true; or 
     &false;. 
    </simpara>

    <note>
     <simpara>
      The boolean type was introduced in PHP 4.
     </simpara>
    </note>

    <sect2 id="language.types.boolean.syntax">
     <title>Syntax</title>
     <para>
      To specify a boolean literal, use either the keyword &true; 
      or &false;. Both are case-insensitive.
      <!-- technically they are just constants -->
      <informalexample>
       <programlisting role="php">
<![CDATA[
$foo = True; // assign the value TRUE to $foo     
]]>
       </programlisting>
      </informalexample>
     </para>
     <para>
      Usually you 
      use some kind of <link linkend="language.operators">operator</link>
      which returns a <type>boolean</type> value, and then pass it 
      on to a <link linkend="control-structures">control
      structure</link>.
      <informalexample>
       <programlisting role="php">
<![CDATA[
// == is an operator which 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 you can simply type this:
if ($show_separators) {
    echo "<hr>\n";
}
]]>
       </programlisting>
      </informalexample>
     </para>
    </sect2>

    <sect2 id="language.types.boolean.casting">
     <title>Converting to boolean</title>
      <simpara>
       To explicitly convert a value to <type>boolean</type>, use either
       the <literal>(bool)</literal> or the <literal>(boolean)</literal> cast.
       However, in most cases you do not need to use the cast, since a value
       will be automatically converted if an operator, function or 
       control structure requires a <type>boolean</type> argument.
      </simpara>
      <simpara>
       See also <link linkend="language.types.type-juggling">Type Juggling</link>.
      </simpara>
      
      <para>
       When converting to <type>boolean</type>, the following values 
       are considered &false;:
  
       <itemizedlist>
        <listitem>
         <simpara>the <link linkend="language.types.boolean">boolean</link> 
          &false;<!-- duh... --></simpara>
        </listitem>
        <listitem>
         <simpara>the <link linkend="language.types.integer">integer</link
         > 0 (zero) </simpara>
        </listitem>
        <listitem>
         <simpara>the <link linkend="language.types.float">float</link> 
         0.0 (zero) </simpara>
        </listitem>
        <listitem>
         <simpara>the empty <link linkend="language.types.string"
           >string</link>, and the <link linkend="language.types.string"
           >string</link>
           "0"</simpara>
        </listitem>
        <listitem>
         <simpara>an <link linkend="language.types.array">array</link> 
         with zero elements</simpara>
        </listitem>
        <listitem>
         <simpara>an <link linkend="language.types.object">object</link> 
         with zero elements</simpara>
        </listitem>
        <listitem>
         <simpara>the special type <link linkend="language.types.null"
           >NULL</link> (including unset variables)
         </simpara>
        </listitem>
       </itemizedlist>
       
       Every other value is considered &true; (including any 
       <link linkend="language.types.resource">resource</link>).
       <warning>
        <simpara>
         <literal>-1</literal> is considered  
         &true;, like any other non-zero (whether negative
         or positive) number!
        </simpara>
       </warning>
       <!-- TODO: add a few examples, for the people only looking at 
            the examples... -->
      </para>
     
    </sect2>

   </sect1>

   <sect1 id="language.types.integer">
    <title>Integers</title>
    
    <simpara>
     An <type>integer</type> is a number of the set 
     Z = {..., -2, -1, 0, 1, 2, ...}.
    </simpara>
     
    <para>
     See also:
     <link linkend="ref.gmp">Arbitrary precision integers</link> and
     <link linkend="language.types.float">Floating point numbers</link>
    </para>

    <sect2 id="language.types.integer.syntax">
     <title>Syntax</title>
     <simpara>
      Integers can be specified in decimal (10-based), hexadecimal (16-based)
      or octal (8-based) notation, optionally preceded by a sign (- or +).
     </simpara>
     <para>
      If you use the octal notation, you must precede the number with a 
      <literal>0</literal> (zero), to use hexadecimal notation precede
      the number with <literal>0x</literal>.
      <example>
       <title>Integer literals</title>
       <programlisting role="php">
<![CDATA[
$a = 1234; # decimal number
$a = -123; # a negative number
$a = 0123; # octal number (equivalent to 83 decimal)
$a = 0x1A; # hexadecimal number (equivalent to 26 decimal)
]]>
       </programlisting>
      </example>
      <!--

       decimal     : [1-9][0-9]*
                   | 0
       
       hexadecimal : 0[xX][0-9a-fA-F]+
       
       octal       : 0[0-7]+
       
       integer     : [+-]?decimal
                   | [+-]?hexadecimal
                   | [+-]?octal
       
       -->
      The size of an integer is platform-dependent, although a 
      maximum value of about two billion is the usual value 
      (that's 32 bits signed). PHP does not support unsigned
	  integers.
     </para>
    </sect2>
   
    <sect2 id="language.types.integer.overflow">
     <title>Integer overflow</title>
     <para>
      If you specify a number beyond the bounds of the <type>integer</type>
      type, it will be interpreted as a <type>float</type> instead. Also, if
      you perform an operation that results in a number beyond the bounds of
      the <type>integer</type> type, a <type>float</type> will be returned
      instead.

      <informalexample>
       <programlisting role="php">
<![CDATA[
$large_number =  2147483647;
var_dump($large_number);
// output: int(2147483647)

$large_number =  2147483648;
var_dump($large_number);
// output: float(2147483648)

// this goes also for hexadecimal specified integers:
var_dump( 0x80000000 );
// output: float(2147483648)

$million = 1000000;
$large_number =  50000 * $million;
var_dump($large_number);
// output: float(50000000000)
]]>
       </programlisting>
      </informalexample>
      <warning>
       <simpara>
        Unfortunately, there was a bug in PHP so that this
        does not always work correctly when there are negative numbers
        involved. For example: when you do <literal>-50000 *
        $million</literal>, the result will be
        <literal>-429496728</literal>. However, when both operands are
        positive there is no problem.
       </simpara>
       <simpara>
        This is solved in PHP 4.1.0.
       </simpara>
      </warning>
     </para>
     <para>
      There is no integer division operator in PHP.
      <literal>1/2</literal> yields the <type>float</type>
      <literal>0.5</literal>. <!-- See ??? for more information. (with the
      operators, or with type-jug) -->
      <informalexample>
       <programlisting role="php">
<![CDATA[
var_dump( 25/7 );
// output: float(3.5714285714286)
]]>
       </programlisting>
      </informalexample>
     </para>
    </sect2>
   

    <sect2 id="language.types.integer.casting">
     <title>Converting to integer</title>
      <simpara>
       To explicitly convert a value to <type>integer</type>, use either
       the <literal>(int)</literal> or the <literal>(integer)</literal> cast.
       However, in most cases you do not need to use the cast, since a value
       will be automatically converted if an operator, function or 
       control structure requires a <type>integer</type> argument.
      </simpara>
      <simpara>
       See also <link linkend="language.types.type-juggling">type-juggling</link>.
      </simpara>
      
      <sect3 id="language.types.integer.casting.from-boolean">
       <title>From <link linkend="language.types.boolean"
           >booleans</link></title>
       <simpara>
        &false; will yield 
        <literal>0</literal> (zero), and &true; 
        will yield <literal>1</literal> (one).
       </simpara>
      </sect3>

      <sect3 id="language.types.integer.casting.from-float">
       <title>From <link linkend="language.types.float">floating point numbers</link></title> 
       <simpara>
        When converting from float to integer, the number will
        be rounded <emphasis>towards zero</emphasis>.
       </simpara>
       
       <para>
        If the float is beyond the boundaries of integer
        <!-- usually, or is it 'always'? -->
        (usually <literal>+/- 2.15e+9 = 2^31</literal>), 
        the result is undefined, since the float hasn't
        got enough precision to give an exact integer result.
        No warning, not even a notice will be issued in this 
        case!
       </para>
       
       <warning><para>
        Never cast an unknown fraction to <type>integer</type>, as this can
        sometimes lead to unexpected results.
        <informalexample>
         <programlisting role="php">
<![CDATA[
echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
]]>
         </programlisting>
        </informalexample>
        
        See for more information the <link 
        linkend="warn.float-precision">warning 
        about float-precision</link>.
       </para></warning>
      </sect3>
      
      <sect3 id="language.types.integer.casting.from-string">
       <title>From strings</title>
       <simpara>
        See <link linkend="language.types.string.conversion">String 
        conversion</link>
       </simpara>
      </sect3>
      
      <sect3 id="language.types.integer.casting.from-other">
       <title>From other types</title>
       <para>
        <caution>
         <simpara>
          Behaviour of converting to integer is undefined for other
          types. Currently, the behaviour is the same as if the value
          was first <link linkend="language.types.boolean.casting"
          >converted to boolean</link>. However, do
          <emphasis>not</emphasis> relay on this behaviour, as it can
          change without notice.
         </simpara>
        </caution>
       </para>
       <!--
        
        IMO, it would more sense as (int) $arr returned the 
        number of elements in $arr. This won't break anything,
        since this behaviour was never defined before, and 
        (bool)(int) $arr will still behave the same.
        
        -->
      </sect3>
      
    </sect2>
  </sect1>

  <sect1 id="language.types.float">
   <title>Floating point numbers</title>
   <para>
    Floating point numbers (AKA "floats", "doubles" or "real numbers") can be 
    specified using any of the following syntaxes: 
    <synopsis>
$a = 1.234; $a = 1.2e3; $a = 7E-10;
    </synopsis>
    <!--  
    
LNUM	[0-9]+
DNUM	([0-9]*[\.][0-9]+)|([0-9]+[\.][0-9]*)
EXPONENT_DNUM	(({LNUM}|{DNUM})[eE][+-]?{LNUM})
    
    -->
    The size of a float is platform-dependent, 
    although a maximum of ~1.8e308 with a precision of roughly 14 
    decimal digits is a common value (that's 64 bit IEEE format).
   </para>
   <warning id="warn.float-precision">
    <title>Floating point precision</title>
    <para>
     It is quite usual that simple decimal fractions like
     <literal>0.1</literal> or <literal>0.7</literal> cannot be
     converted into their internal binary counterparts without a
     little loss of precision. This can lead to confusing results: for
     example, <literal>floor((0.1+0.7)*10)</literal> will usually
     return <literal>7</literal> instead of the expected
     <literal>8</literal> as the result of the internal representation
     really being something like <literal>7.9999999999...</literal>.
    </para>
    <para>
     This is related to the fact that it is impossible to exactly
     express some fractions in decimal notation with a finite number
     of digits. For instance, <literal>1/3</literal> in decimal form
     becomes <literal>0.3333333. . .</literal>.
    </para>
    <para>
     So never trust floating number results to the last digit and
     never compare floating point numbers for equality. If you really
     need higher precision, you should use the <link
     linkend="ref.bc">arbitrary precision math functions</link>
     or <link linkend="ref.gmp">gmp</link> functions instead.
    </para>
   </warning>
  </sect1>

  <sect1 id="language.types.string">
   <title>Strings</title>
   <para>
    A <type>string</type> is series of characters. In PHP,
    a character is the same as a byte, that is, there are exactly
    256 different characters possible. This also implies that PHP
    has no native support of Unicode. 
    <!-- how about unicode? will we support that eventually? Are
    there current any ways to work with unicode?
    -->
   </para>
   <note>
    <simpara>
     It is no problem for a string to become very large. 
     There is no practical bound to the size
     of strings imposed by PHP, so there is no reason at all
     to worry about long strings.
    </simpara>
   </note>
   <sect2 id="language.types.string.syntax">
    <title>Syntax</title>
    <para>
     A string literal can be specified in three different
     ways.
     <itemizedlist>

      <listitem>
       <simpara>
        <link linkend="language.types.string.syntax.single">single quoted</link>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <link linkend="language.types.string.syntax.double">double quoted</link>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <link linkend="language.types.string.syntax.heredoc">heredoc syntax</link>
       </simpara>
      </listitem>

     </itemizedlist>
    </para>
    <sect3 id="language.types.string.syntax.single">
     <title>Single quoted</title>
     <para>
      The easiest way to specify a simple string is to
      enclose it in single quotes (the character <literal>'</literal>). 
     </para>
     <para>
      To specify a       literal single
      quote, you will need to escape it with a backslash
      (<literal>\</literal>), like in many other languages.
      If a backslash needs to occur before a single quote or at 
      the end of the string, you need to double it.
      Note that if you try to escape any
      other character, the backslash too will be printed! So
      usually there is no need to escape the backslash itself.
      <note>
       <simpara>
        In PHP 3, a warning will
        be issued at the <literal>E_NOTICE</literal> level when this
        happens.        
       </simpara>
      </note>
      <note>
       <simpara>
        Unlike the two other syntaxes, variables will <emphasis>not</emphasis> 
        be expanded when they occur in single quoted strings.
       </simpara>
      </note>
      <informalexample>
       <programlisting role="php">
<![CDATA[
echo 'this is a simple string';
echo 'You can also have embedded newlines in strings,
like this way.';
echo 'Arnold once said: "I\'ll be back"';
// output: ... "I'll be back"
echo 'Are you sure you want to delete C:\\*.*?';
// output: ... delete C:\*.*?
echo 'Are you sure you want to delete C:\*.*?';
// output: ... delete C:\*.*?
echo 'I am trying to include at this point: \n a newline';
// output: ... this point: \n a newline
]]>
       </programlisting>
      </informalexample>
     </para>
    </sect3>
    <sect3 id="language.types.string.syntax.double">
     <title>Double quoted</title>
     <para>
      If the string is enclosed in double-quotes ("),
      PHP understands more escape sequences for special
      characters:
     </para>
     <table>
      <title>Escaped characters</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>sequence</entry>
         <entry>meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><literal>\n</literal></entry>
         <entry>linefeed (LF or 0x0A (10) in ASCII)</entry>
        </row>
        <row>
         <entry><literal>\r</literal></entry>
         <entry>carriage return (CR or 0x0D (13) in ASCII)</entry>
        </row>
        <row>
         <entry><literal>\t</literal></entry>
         <entry>horizontal tab (HT or 0x09 (9) in ASCII)</entry>
        </row>
        <row>
         <entry><literal>\\</literal></entry>
         <entry>backslash</entry>
        </row>
        <row>
         <entry><literal>\$</literal></entry>
         <entry>dollar sign</entry>
        </row>
        <row>
         <entry><literal>\"</literal></entry>
         <entry>double-quote</entry>
        </row>
        <row>
         <entry><literal>\[0-7]{1,3}</literal></entry>
         <entry>
          the sequence of characters matching the regular
          expression is a character in octal notation
         </entry>
        </row>
        <row>
         <entry><literal>\x[0-9A-Fa-f]{1,2}</literal></entry>
         <entry>
          the sequence of characters matching the regular
          expression is a character in hexadecimal notation
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     <para>
      Again, if you try to escape any other character, the
      backslash will be printed too!
     </para>
     <para>
      But the most important pre of double-quoted strings
      is the fact that variable names will be expanded.
      See <link linkend="language.types.string.parsing">string 
      parsing</link> for details.
     </para>
    </sect3>
    
    <sect3 id="language.types.string.syntax.heredoc">
     <title>Heredoc</title>
     <simpara>
      Another way to delimit strings is by using here doc syntax
      ("&lt;&lt;&lt;").  One should provide an identifier after
      <literal>&lt;&lt;&lt;</literal>, then the string, and then the
      same identifier to close the quotation. 
     </simpara>     
     <simpara>
      The closing identifier <emphasis>must</emphasis> begin in the
      first column of the line.  Also, the identifier used must follow
      the same naming rules as any other label in PHP: it must contain
      only alphanumeric characters and underscores, and must start with
      a non-digit character or underscore.
     </simpara>
     
     <warning>
      <simpara>
       It is very important to note that the line with the closing
       identifier contains no other characters, except 
       <emphasis>possibly</emphasis> a semicolon (<literal>;</literal>).
       That means especially that the identifier 
       <emphasis>may not be indented</emphasis>, and there
       may not be any spaces or tabs after or before the semicolon.
      </simpara>
      <simpara>
       Probably the nastiest gotcha is that there may also
       not be a carriage return (<literal>\r</literal>) at the end of 
       the line, only 
       a form feed, AKA newline (<literal>\n</literal>).
       Since Microsoft Windows uses the sequence 
       <literal>\r\n</literal> as a line
       terminator, your heredoc may not work if you write your
       script in a Windows editor. However, most programming
       editors provide a way to save your files with a UNIX
       line terminator.
       <!--
       FTP will sometimes automatically convert \r\n to \n while
       transferring your files to your webserver (which
       is *nix, of course)
       -->
      </simpara>
     </warning>

     <para>
      Here doc text behaves just like a double-quoted string, without
      the double-quotes. This means that you do not need to escape quotes
      in your here docs, but you can still use the escape codes listed
      above. Variables are expanded, but the same care must be taken
      when expressing complex variables inside a here doc as with
      strings.
      <example> 
       <title>Here doc string quoting example</title>
       <programlisting role="php">
<![CDATA[
<?php
$str = <<<EOD
Example of string
spanning multiple lines
using heredoc syntax.
EOD;

/* More complex example, with variables. */
class foo
{
    var $foo;
    var $bar;

    function foo()
    {
        $this->foo = 'Foo';
        $this->bar = array('Bar1', 'Bar2', 'Bar3');
    }
}

$foo = new foo();
$name = 'MyName';

echo <<<EOT
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should print a capital 'A': \x41
EOT;
?>
]]>
       </programlisting>
      </example>
     </para>
  
     <note>
      <para>
       Here doc support was added in PHP 4.
      </para>
     </note>
  
    </sect3>
    <sect3 id="language.types.string.parsing">
     <title>Variable parsing</title>
     <simpara>
      When a string is specified in double quotes or with
      heredoc, variables are
      parsed within it. 
     </simpara>
     <simpara>
      There are two types of syntax, a 
      <link linkend="language.types.string.parsing.simple">simple</link>
      one and a 
      <link linkend="language.types.string.parsing.complex">complex</link>
      one.
      The simple syntax is the most common and convenient, it provides a way
      to parse a variable, an array value, or an object property.
     </simpara>
     <simpara>
      The complex syntax was introduced in PHP 4,
      <!-- XXX was it? and starting with what version exactly? -->
      and can by recognised
      by the curly braces surrounding the expression.
     </simpara>
     <sect4 id="language.types.string.parsing.simple">
      <title>Simple syntax</title>
      <simpara>
       If a dollar sign (<literal>$</literal>) is encountered, the
       parser will greedily take as much tokens as possible to form a
       valid variable name. Enclose the variable name in curly
       braces if you want to explicitly specify the end of the name.
      </simpara>
      <informalexample>
       <programlisting role="php">
<![CDATA[
$beer = 'Heineken';
echo "$beer's taste is great"; // works, "'" is an invalid character for varnames
echo "He drunk some $beers"; // won't work, 's' is a valid character for varnames
echo "He drunk some ${beer}s"; // works
]]>
       </programlisting>
      </informalexample>
      <simpara>
       Similarly, you can also have an array index or an object
       property parsed. With array indices, the closing square bracket
       (<literal>]</literal>) marks the end of the index. For
       object properties the same rules apply as to simple variables,
       though with object properties there doesn't exist a trick like
       the one with variables.
       
       <!-- XXX isn't &true; :(, this would be the trick
       Also,
       the same trick with curly-braces works if you
       want to limit the greediness of parsers (aren't they
       paying them enough or something?).
       -->
      
      </simpara>
      <informalexample>
       <programlisting role="php">
<![CDATA[
$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' );

// note that this works differently outside string-quotes.
echo "A banana is $fruits[banana].";

echo "This square is $square->width meters broad.";

// Won't work. For a solution, see the complex syntax.
echo "This square is $square->width00 centimeters broad.";

]]>
<!-- XXX this won't work:
echo "This square is $square->{width}00 centimeters broad."; 
// XXX: php developers: it would be consequent to make this work.
// XXX: like the $obj->{expr} syntax outside a string works, 
// XXX: analogously to the ${expr} syntax for variable var's.
-->
       </programlisting>
      </informalexample>
      <simpara>
       For anything more complex, you should use the complex syntax.
      </simpara>
     </sect4>
     <sect4 id="language.types.string.parsing.complex">
      <title>Complex (curly) syntax</title>
      <simpara>
       This isn't called complex because the syntax is complex,
       but because you can include complex expressions this way.
     </simpara>
     <simpara>
      In fact, you can include any value that is in the namespace
      in strings with this syntax. You simply write the expression
      the same way as you would outside the string, and then include
      it in { and }. Since you can't escape '{', this syntax will
      only be recognised when the $ is immediately following the {.
      (Use "{\$" or "\{$" to get a literal "{$").
      Some examples to make it clear:
     </simpara>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$great = 'fantastic';
echo "This is { $great}"; // won't work, outputs: This is { fantastic}
echo "This is {$great}";  // works, outputs: This is fantastic
echo "This square is {$square->width}00 centimeters broad."; 
echo "This works: {$arr[4][3]}";     

// This is wrong for the same reason
// as $foo[bar] is wrong outside a string. 
echo "This is wrong: {$arr[foo][3]}"; 

echo "You should do it this way: {$arr['foo'][3]}";
echo "You can even write {$obj->values[3]->name}";
echo "This is the value of the var named $name: {${$name}}";
]]>
<!-- maybe it's better to leave this out?? 
// this works, but i disencourage its use, since this is NOT 
// involving functions, rather than mere variables, arrays and objects.
$beer = 'Heineken';
echo "I'd like to have another {${ strrev('reeb') }}, hips";
 -->
       </programlisting>
      </informalexample>
     </sect4>
    </sect3>
    
    <sect3 id="language.types.string.substr">
     <title>String access by character</title>
     <para>
      Characters within strings may be accessed by specifying the
      zero-based offset of the desired character after the string 
      in curly braces.
     </para>
     <note>
      <simpara>
       For backwards compatibility, you can still use the array-braces.
       However, this syntax is deprecated as of PHP 4.
      </simpara>
     </note>
     <para>
      <example>
       <title>Some string examples</title>
       <programlisting role="php">
<!-- TODO: either move these examples to a example section,
as with arrays, or distribute them under the applicable
sections. -->
<![CDATA[
<?php
/* Assigning a string. */
$str = "This is a string";

/* Appending to it. */
$str = $str . " with some more text";

/* Another way to append, includes an escaped newline. */
$str .= " and a newline at the end.\n";

/* This string will end up being '<p>Number: 9</p>' */
$num = 9;
$str = "<p>Number: $num</p>";

/* This one will be '<p>Number: $num</p>' */
$num = 9;
$str = '<p>Number: $num</p>';

/* Get the first character of a string  */
$str = 'This is a test.';
$first = $str{0};

/* Get the last character of a string. */
$str = 'This is still a test.';
$last = $str{strlen($str)-1};
?>
]]>
       </programlisting>
      </example>
     </para>
    </sect3>

   </sect2><!-- end syntax -->

   <sect2 id="language.types.string.useful-funcs">
    <title>Useful functions</title><!-- and operators -->
    <para>
     Strings may be concatenated using the '.' (dot) operator. Note
     that the '+' (addition) operator will not work for this. Please
     see <link linkend="language.operators.string">String
     operators</link> for more information.
    </para>
    <para>
     There are a lot of useful functions for string modification.
    </para>
    <simpara>
     See the <link linkend="ref.strings">string functions section</link> 
     for general functions, the regular expression functions for
     advanced find&amp;replacing (in two tastes: 
     <link linkend="ref.pcre">Perl</link> and 
     <link linkend="ref.regex">POSIX extended</link>).
    </simpara>
    <simpara>
     There are also <link linkend="ref.url">functions for URL-strings</link>,
     and functions to encrypt/decrypt strings 
     (<link linkend="ref.mcrypt">mcrypt</link> and 
     <link linkend="ref.mhash">mhash</link>).
    </simpara>
    <simpara>
     Finally, if you still didn't find what you're looking for,
     see also the <link linkend="ref.ctype">character type functions</link>.
    </simpara>
   </sect2>
   <sect2 id="language.types.string.conversion">
    <title>String conversion</title>

    <simpara>
     When a string is evaluated as a numeric value, the resulting
     value and type are determined as follows.
    </simpara>
    <simpara>
     The string will evaluate as a <type>float</type> if it contains any of the
     characters '.', 'e', or 'E'. Otherwise, it will evaluate as an
     integer.
    </simpara>
    <para>
     The value is given by the initial portion of the string. If the
     string starts with valid numeric data, this will be the value
     used. Otherwise, the value will be 0 (zero). Valid numeric data
     is an optional sign, followed by one or more digits (optionally
     containing a decimal point), followed by an optional
     exponent. The exponent is an 'e' or 'E' followed by one or more
     digits.
    </para>
    <simpara>
     When the first expression is a string, the type of the variable
     will depend on the second expression.
    </simpara>
    <informalexample>
     <programlisting role="php">
<![CDATA[
$foo = 1 + "10.5";              // $foo is float (11.5)
$foo = 1 + "-1.3e3";            // $foo is float (-1299)
$foo = 1 + "bob-1.3e3";         // $foo is integer (1)
$foo = 1 + "bob3";              // $foo is integer (1)
$foo = 1 + "10 Small Pigs";     // $foo is integer (11)
$foo = 1 + "10 Little Piggies"; // $foo is integer (11)
$foo = "10.0 pigs " + 1;        // $foo is integer (11)
$foo = "10.0 pigs " + 1.0;      // $foo is float (11)     
]]>
     </programlisting>
    </informalexample>
    <simpara>
     For more information on this conversion, see the Unix manual page
     for strtod(3).
    </simpara>
    <para>
     If you would like to test any of the examples in this section,
     you can cut and paste the examples and insert the following line
     to see for yourself what's going on:
     <informalexample>
      <programlisting role="php">
<![CDATA[
echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n";
]]>
      </programlisting>
     </informalexample>
    </para>

   </sect2>
  </sect1><!-- end string -->

  <sect1 id="language.types.array">
   <title>Arrays</title>

   <para>
    An array in PHP is actually an ordered map. A map is a type that
    maps <emphasis>values</emphasis> to <emphasis>keys</emphasis>. 
    This type is optimized in several ways,
    so you can use it as a real array, or a list (vector), 
    hashtable (which is an implementation of a map), 
    dictionary, <!-- is a map -->
    collection,
    stack, queue and probably more. Because you can have another
    PHP-array as a value, you can also quite easily simulate
    trees.
   </para>
   <para>
    Explanation of those structures is beyond the scope of this manual,
    but you'll find at least one example for each of those structures.
    For more information about those structures, we refer you to
    external literature about this broad topic. 
    <!-- like goodrich&tamassia: datastructures and algorithmes.
    Only, the subtitle is: in Java, and it's quite academic too -->
   </para>
   
   <sect2 id="language.types.array.syntax">
    <title>Syntax</title>
    
    <sect3 id="language.types.array.syntax.array-func">
     <title>Specifying with <function>array</function></title>
     <para>
      An <type>array</type> can be created by the <function>array</function> 
      language-construct. It takes a certain number of comma-separated
      <literal><replaceable>key</replaceable> =&gt; <replaceable
      >value</replaceable></literal>
      pairs. 
     </para>
     <para>
      A <varname>key</varname> is either a nonnegative <type>integer</type> 
      <!-- 
      
      Negative integers are also allowed, however, IMO it's best to not 
      document that, or even disencourage it. 
      
      Why?
      
      First, because it is very tricky. But the real reason is that the key
      '-1' will be interpreted as a string, and not as a integer. Therefore,
      the usage
      
      "the -1'st value of \$arr is $arr[-1]" is ambigious. By the way,
      it results in a parse-error anyway, which is another argument for
      not documenting it.
      
      -Jeroen
      
      -->
      or a <type>string</type>.
      If a key is the standard representation of a non-negative 
      <type>integer</type>, it will
      be interpreted as such (i.e. <literal>'8'</literal> will be interpreted 
      as <literal>8</literal>, while
      <literal>'08'</literal> will be interpreted as <literal>'08'</literal>).
     </para>
     <para>
      A value can be anything.
     </para>
     <para>
      If you omit a key, the maximum of the integer-indices is taken, and
      the new key will be that maximum + 1. If no integer-indices exist
      yet, the key will be <literal>0</literal> (zero). If you specify a key
      that already has a value assigned to it, that value will be overwritten.
     </para>
     
     <para>
      <synopsis>
array( <optional> <replaceable>key</replaceable> =&gt; </optional> <replaceable
>value</replaceable>
     , ...
     )
// <replaceable>key</replaceable> is either <type>string</type
                        > or nonnegative <type>integer</type>
// <replaceable>value</replaceable> can be anything
      </synopsis>
     </para>
    </sect3>
    
    <sect3 id="language.types.array.syntax.modifying">
     <title>Creating/modifying with square-bracket syntax</title>
     <para>
      You can also modify an existing array, by explicitly setting
      values.
     </para>
     <para>
      This is done by assigning values to the array while specifying the 
      key in brackets. You can also 
      omit the key, 
      add an empty pair
      of brackets ("<literal>[]</literal>") to the variable-name in that case.
      <synopsis>
$arr[<replaceable>key</replaceable>] = <replaceable>value</replaceable>;
$arr[] = <replaceable>value</replaceable>;
// <replaceable>key</replaceable> is either <type>string</type
                        > or nonnegative <type>integer</type>
// <replaceable>value</replaceable> can be anything
      </synopsis>
      If <varname>$arr</varname> doesn't exist yet, it will be created. 
      So this is also
      an alternative way to specify an array.
      To change a certain value, just assign a new value
      to it.
      If you want to remove a key/value pair, you need to 
      <function>unset</function> it. 
      
     </para>

    </sect3>
    

   </sect2><!-- end syntax -->
   
   <sect2 id="language.types.array.useful-funcs">
    <title>Useful functions</title>
    <para>
     There are quite some useful function for working
     with arrays, see the <link linkend="ref.array">array-functions</link> 
     section.
    </para>
    <note>
     <para>
      The <function>unset</function> function allows unsetting keys of an 
      array. Be aware that the array will NOT be reindexed.
      <informalexample>
       <programlisting role="php">
<![CDATA[
$a = array( 1 => 'one', 2 => 'two', 3 => 'three' );
unset( $a[2] );
/* will produce an array that would have been defined as
   $a = array( 1=>'one', 3=>'three');
   and NOT
   $a = array( 1 => 'one', 2 => 'three');
*/   
]]>
      </programlisting>
     </informalexample>
     
     </para>    
    </note> 
    <para>
     The <link linkend="control-structures.foreach">foreach</link> 
     control structure exists specificly for arrays. It 
     provides an easy way to traverse an array.
    </para>
    
    
   </sect2>
   
   <sect2 id="language.types.array.donts">
    <title>Array do's and don'ts</title>

    <sect3 id="language.types.array.foo-bar">
     <title>Why is <literal>$foo[bar]</literal> wrong?</title>
     <para>
      You might have seen the following syntax in old scripts:
      <informalexample>
       <programlisting role="php">
<![CDATA[
$foo[bar] = 'enemy';
echo $foo[bar];
// etc
]]>
       </programlisting>
      </informalexample>
      This is wrong, but it works. Then, why is it wrong? The reason is 
      that, as stated in the <link linkend="language.types.array.syntax"
      >syntax</link> section, there must be an expression between the 
      square brackets ('<literal>[</literal>' and '<literal>]</literal>').
      That means that you can write things like this:
      <informalexample>
       <programlisting role="php">
<![CDATA[
echo $arr[ foo(true) ];        
]]>
       </programlisting>
      </informalexample>
      This is an example of using a function return value
      as the array index. PHP knows also about constants,
      and you may have seen the
      <literal>E_*</literal> before.      

      <informalexample>
       <programlisting role="php">
<![CDATA[
$error_descriptions[E_ERROR] = "A fatal error has occured";
$error_descriptions[E_WARNING] = "PHP issued a warning";
$error_descriptions[E_NOTICE] = "This is just an informal notice";
]]>
       </programlisting>
      </informalexample>
      Note that <literal>E_ERROR</literal> is also a valid identifier, 
      just like <literal>bar</literal> in the first example. But the last
      example is in fact the same as writing:
      <informalexample>
       <programlisting role="php">
<![CDATA[
$error_descriptions[1] = "A fatal error has occured";
$error_descriptions[2] = "PHP issued a warning";
$error_descriptions[8] = "This is just an informal notice";
]]>
       </programlisting>
      </informalexample>
      because <literal>E_ERROR</literal> equals <literal>1</literal>, etc.
     </para>
     <para>
      Then, how is it possible that <literal>$foo[bar]</literal> works?
      It works, because <literal>bar</literal> is due to its syntax
      expected to be a constant expression. However, in this case no 
      constant with the name <literal>bar</literal> exists. PHP now
      assumes that you meant <literal>bar</literal> literally, 
      as the string <literal>"bar"</literal>, but that you forgot
      to write the quotes.
     </para>
     <sect4>
      <title>So why is it bad then?</title>
      <para>
       At some point in the future, the PHP team might want to add another
       constant or keyword, and then you get in trouble. For example,
       you already cannot use the words <literal>empty</literal> and 
       <literal>default</literal> this way, since they are special keywords.
       <!-- <jeroen>hmm... i'm doubting this myself. Finish it if you like</jeroen>
       But probably 
       the most threatening
       thing is yourself, or whoever will maintain the script. You'll 
       maybe get very strange behaviour, and 
       -->
      </para>
      <para>
       And, if these arguments don't help: this syntax is simply deprecated,
       and it might stop working some day.
      </para>
      <note>
       <simpara>
        When you turn <link linkend="function.error-reporting"
        >error_reporting</link> to <literal>E_ALL</literal>,
        you will see that PHP generates warnings whenever this construct
        is used. This is also valid for other deprecated 'features'.
        (put the line <literal>error_reporting(E_ALL);</literal> 
        in your script)
       </simpara>
      </note>
      <note>
       <simpara>
        Inside a double-quoted <type>string</type>, an other syntax
        is valid. See <link linkend="language.types.string.parsing"
        >variable parsing in strings</link> for more details.
       </simpara>
      </note>
     </sect4>
    </sect3>
   </sect2>

   <sect2 id="language.types.array.examples">
    <title>Examples</title>
    <para>
     The array type in PHP is very versatile, so here will be some 
     examples to show you the full power of arrays.
    </para>
    <para>
      <informalexample>
       <programlisting role="php">
<![CDATA[
// this
$a = array( 'color' => 'red'
          , 'taste' => 'sweet'
          , 'shape' => 'round'
          , 'name'  => 'apple'
          ,            4        // key will be 0
          );

// is completely equivalent with
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name'] = 'apple';
$a[]        = 4;        // key will be 0

$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// will result in the array array( 0 => 'a' , 1 => 'b' , 2 => 'c' ),
// or simply array('a', 'b', 'c')
]]>
       </programlisting>
      </informalexample>
     </para>
    
    <example>
     <title>Using array()</title>
     <programlisting role="php">
<![CDATA[
// Array as (property-)map
$map = array( 'version'    => 4
            , 'OS'         => 'Linux'
            , 'lang'       => 'english'
            , 'short_tags' => true
            );
            
// strictly numerical keys
$array = array( 7
              , 8
              , 0
              , 156
              , -10
              );
// this is the same as array( 0 => 7, 1 => 8, ...)

$switching = array(         10 // key = 0
                  , 5    =>  6
                  , 3    =>  7 
                  , 'a'  =>  4
                  ,         11 // key = 6 (maximum of integer-indices was 5)
                  , '8'  =>  2 // key = 8 (integer!)
                  , '02' => 77 // key = '02'
                  , 0    => 12 // the value 10 will be overwritten by 12
                  );
                  
// empty array
$empty = array();         
]]>
<!-- TODO example of
- mixed keys
- overwriting keys
- integer keys as string
- using vars/functions as key/values
- mixed skipping
-->
     </programlisting>
    </example>

    <example id="language.types.array.examples.loop">
     <title>Collection</title>
     <programlisting role="php">
<![CDATA[
$colors = array('red','blue','green','yellow');

foreach ( $colors as $color ) {
    echo "Do you like $color?\n";
}

/* output:
Do you like red?
Do you like blue?
Do you like green?
Do you like yellow?
*/
]]>
     </programlisting>
    </example>
    
    <para>
     Note that it is currently not possible to change the values of the array
     directly in such a loop. 
      <!--
       Should be made possible, if you write:
       foreach ( $colors as &$color )
      
       See bug#3074
      -->
     A workaround is the following: 
     <example id="language.types.array.examples.changeloop">
      <title>Collection</title>
      <programlisting role="php">
<![CDATA[
foreach ($colors as $key => $color) {
    // won't work:
    //$color = strtoupper($color);
    
    //works:
    $colors[$key] = strtoupper($color);
}
print_r($colors);

/* output:
Array
(
    [0] => RED
    [1] => BLUE
    [2] => GREEN
    [3] => YELLOW
)
*/
]]>
      </programlisting>
     </example>
    </para>
    <para>
     This example creates a one-based array.
     <example>
      <title>One-based index</title>
      <programlisting role="php">
<![CDATA[
$firstquarter  = array(1 => 'January', 'February', 'March');
print_r($firstquarter);

/* output:
Array 
(
    [1] => 'January'
    [2] => 'February'
    [3] => 'March'
)
*/
]]>   
      </programlisting>
     </example>
    </para>
    <example>
     <title>Filling real array</title>
     <programlisting role="php">
<![CDATA[
// fill an array with all items from a directory
$handle = opendir('.');
while ($file = readdir($handle)) 
{
    $files[] = $file;
}
closedir($handle); 
]]>
     </programlisting>
    </example>
    <para>
     Arrays are ordered. You can also change the order using various
     sorting-functions. See <link linkend="ref.array">array-functions</link> 
     for more information.
    </para>
    <example>
     <title>Sorting array</title>
     <programlisting role="php">
<![CDATA[
sort($files);
print_r($files);
]]>
     </programlisting>
    </example>
    <para>
     Because the value of an array can be everything, it can also be 
     another array. This way you can make recursive and
     multi-dimensional arrays.
    </para>
    <example>
     <title>Recursive and multi-dimensional arrays</title>
     <programlisting role="php">
<![CDATA[
$fruits = array ( "fruits"  => array ( "a" => "orange"
                                     , "b" => "banana"
                                     , "c" => "apple"
                                     )
                , "numbers" => array ( 1
                                     , 2
                                     , 3
                                     , 4
                                     , 5
                                     , 6
                                     )
                , "holes"   => array (      "first"
                                     , 5 => "second"
                                     ,      "third"
                                     )
                );
]]>
<!-- quite duplicate...
$a = array(
     "apple"  => array(
          "color"  => "red",
          "taste"  => "sweet",
          "shape"  => "round"
     ),
     "orange"  => array(
          "color"  => "orange",
          "taste"  => "tart",
          "shape"  => "round"
     ),
     "banana"  => array(
          "color"  => "yellow",
          "taste"  => "paste-y",
          "shape"  => "banana-shaped"
     )
);
-->
     </programlisting>
    </example>

   </sect2>
   
   <!-- TODO
   <sect2>
    <title>Misc</title>
   
   </sect2>
   
   - example multi-dim with $arr[bla][bla] syntax
   - converting to array
   - warning about references
   - note that assigning is copy (usually...)
   
   
   -->  

<!-- there is no such thing as multi/singel dim arrays (at least in PHP4) 
   <sect2 id="language.types.array.single-dim">
    <title>Single Dimension Arrays</title>

    <para>
     PHP supports both scalar and associative arrays. In fact, there
     is no difference between the two.  You can create an array using
     the 
     
     <function>list</function> 
     
     Nope
     
     
     
     
     or <function>array</function>
     functions, or you can explicitly set each array element value.
     <informalexample>
      <programlisting role="php"> 
$a[0] = "abc"; 
$a[1] = "def"; 
$b["foo"] = 13;
      </programlisting>
     </informalexample>
    </para>
    <para>
     You can also create an array by simply adding values to the
     array. When you assign a value to an array variable using empty
     brackets, the value will be added onto the end of the array.
     <informalexample>
      <programlisting role="php"> 
$a[] = "hello"; // $a[2] == "hello"
$a[] = "world"; // $a[3] == "world" 
      </programlisting>
     </informalexample>
    </para>
    <para>
     Arrays may be sorted using the <function>asort</function>,
     <function>arsort</function>, <function>ksort</function>,
     <function>rsort</function>, <function>sort</function>,
     <function>uasort</function>, <function>usort</function>, and
     <function>uksort</function> functions depending on the type of
     sort you want.
    </para>
    <para>
     You can count the number of items in an array using the
     <function>count</function> function.
    </para>
    <para>
     You can traverse an array using <function>next</function> and
     <function>prev</function> functions.  Another common way to
     traverse an array is to use the <function>each</function>
     function.
    </para>
   </sect2>

   <sect2 id="language.types.array.multi-dim">
    <title>Multi-Dimensional Arrays</title>

    <para>
     Multi-dimensional arrays are actually pretty simple.  For each
     dimension of the array, you add another [key] value to the end:
     <informalexample>
      <programlisting role="php"> 
$a[1]      = $f;               # one dimensional examples
$a["foo"]  = $f;   

$a[1][0]     = $f;             # two dimensional
$a["foo"][2] = $f;             # (you can mix numeric and associative indices)
$a[3]["bar"] = $f;             # (you can mix numeric and associative indices)

$a["foo"][4]["bar"][0] = $f;   # four dimensional!
      </programlisting>
     </informalexample>
    </para>
    <para>
     In PHP 3 it is not possible to reference multidimensional arrays
     directly within strings. For instance, the following will not
     have the desired result:
     <informalexample>
      <programlisting role="php"> 
$a[3]['bar'] = 'Bob';
echo "This won't work: $a[3][bar]";
      </programlisting>
     </informalexample>
     In PHP 3, the above will output <computeroutput>This won't work:
     Array[bar]</computeroutput>. The string concatenation operator,
     however, can be used to overcome this:
     <informalexample>
      <programlisting role="php">
$a[3]['bar'] = 'Bob';
echo "This will work: " . $a[3]['bar'];
      </programlisting>
     </informalexample>
    </para>
    <para>
     In PHP 4, however, the whole problem may be circumvented by
     enclosing the array reference (inside the string) in curly
     braces:
     <informalexample>
      <programlisting role="php">
$a[3]['bar'] = 'Bob';
echo "This will work: {$a[3][bar]}";
      </programlisting>
     </informalexample>
    </para>
    <para>
     You can "fill up" multi-dimensional arrays in many ways, but the
     trickiest one to understand is how to use the
     <function>array</function> command for associative arrays.  These
     two snippets of code fill up the one-dimensional array in the
     same way:
     <informalexample>
      <programlisting role="php"> 
# Example 1:

$a["color"]	= "red";
$a["taste"]	= "sweet";
$a["shape"]	= "round";
$a["name"]	= "apple";
$a[3]		= 4;

# Example 2:
$a = array(
     "color" => "red",
     "taste" => "sweet",
     "shape" => "round",
     "name"  => "apple",
     3       => 4
);
      </programlisting>
     </informalexample>
    </para>
    <para>
     The <function>array</function> function can be nested for
     multi-dimensional arrays:
     <informalexample>
      <programlisting role="php"> 
&lt;?php
$a = array(
     "apple"  => array(
          "color"  => "red",
          "taste"  => "sweet",
          "shape"  => "round"
     ),
     "orange"  => array(
          "color"  => "orange",
          "taste"  => "tart",
          "shape"  => "round"
     ),
     "banana"  => array(
          "color"  => "yellow",
          "taste"  => "paste-y",
          "shape"  => "banana-shaped"
     )
);

echo $a["apple"]["taste"];    # will output "sweet"
?>
      </programlisting>
     </informalexample>
    </para>

   </sect2>
   
   -->
  </sect1>

  <sect1 id="language.types.object">
   <title>Objects</title>

   <sect2 id="language.types.object.init">
    <title>Object Initialization</title>

    <para>
     To initialize an object, you use the <literal>new</literal>
     statement to instantiate the object to a variable.

     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
class foo
{
    function do_foo()
    {
        echo "Doing foo."; 
    }
}

$bar = new foo;
$bar->do_foo();
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     For a full discussion, please read the section <link
     linkend="language.oop">Classes and Objects</link>.
    </simpara>

   </sect2>
  </sect1>

  <sect1 id="language.types.resource">
   <title>Resource</title>
    
    <para>
     A resource is a special variable, holding
     a reference to an external resource. Resources
     are created and used by special functions.
     See the <link linkend="resource">appendix</link> 
     for a listing of all these
     functions and the corresponding resource types.
     
    </para>
    
    <note>
     <simpara>
      The resource type was introduced in PHP 4
     </simpara>
    </note>

    <sect2 id="language.types.resource.self-destruct">
     <title>Freeing resources</title>
    
    <para>
     Due to the reference-counting system introduced
     with PHP4's Zend-engine, it is automatically detected
     when a resource is no longer referred to (just
     like Java). When this is
     the case, all resources that were in use for this 
     resource are made free by the garbage collector.
     For this reason, it is rarely ever necessary to
     free the memory manually by using some free_result
     function.
     <note>
      <simpara>
       Persistent database-links are special, they 
       are <emphasis>not</emphasis> destroyed by the 
       gc. See also <link 
       linkend="features.persistent-connections">persistent 
       links</link>
      </simpara>
     </note>
    </para>
    
   </sect2>
  </sect1>
    
  <sect1 id="language.types.null">
   <title>NULL</title>
    
   <para>
    The special &null; value represents 
    that a variable has no value. &null; is the only possible value of type
    <type>NULL</type>.
   </para>
    <note>
     <simpara>
      The null type was introduced in PHP 4
     </simpara>
    </note>
    
   <sect2 id="language.types.null.syntax">
    <title>Syntax</title>
    <para>
     There is only one value of type &null;, and that is 
     the case-insensitive keyword
     &null;.
     <informalexample>
      <programlisting role="php">
$var = NULL;       
      </programlisting>
     </informalexample>
    </para>
   </sect2>
  
  </sect1>

  <sect1 id="language.types.type-juggling">
   <title>Type Juggling</title>

   <simpara>
    PHP does not require (or support) explicit type definition in
    variable declaration; a variable's type is determined by the
    context in which that variable is used. That is to say, if you
    assign a string value to variable <parameter>var</parameter>,
    <parameter>var</parameter> becomes a string. If you then assign an
    integer value to <parameter>var</parameter>, it becomes an
    integer.
   </simpara>
   <para>
    An example of PHP's automatic type conversion is the addition
    operator '+'. If any of the operands is a float, then all
    operands are evaluated as floats, and the result will be a
    float. Otherwise, the operands will be interpreted as integers,
    and the result will also be an integer. Note that this does NOT
    change the types of the operands themselves; the only change is in
    how the operands are evaluated.
    <informalexample>
     <programlisting role="php">
$foo = "0";  // $foo is string (ASCII 48)
<!-- bad example, no real operator (must be used with variable, modifies it too)
$foo++;      // $foo is the string "1" (ASCII 49)
-->
$foo += 2;   // $foo is now an integer (2)
$foo = $foo + 1.3;  // $foo is now a float (3.3)
$foo = 5 + "10 Little Piggies"; // $foo is integer (15)
$foo = 5 + "10 Small Pigs";     // $foo is integer (15)
<!--

TODO: explain ++/- - behaviour with strings

examples:

++'001' = '002'
++'abc' = 'abd'
++'xyz' = 'xza'
++'9.9' = '9.0'
++'-3'  = '-4'
- -'9'   = 8 (integer!)
- -'5.5' = '5.5'
- -'-9'  = -10 (integer)
- -'09'  = 8 (integer)
- -'abc' = 'abc'

-->
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    If the last two examples above seem odd, see <link
    linkend="language.types.string.conversion">String
    conversion</link>.
   </simpara>
   <simpara>
    If you wish to force a variable to be evaluated as a certain type,
    see the section on <link linkend="language.types.typecasting">Type
    casting</link>. If you wish to change the type of a variable, see
    <function>settype</function>.
   </simpara>
   <para>
    If you would like to test any of the examples in this section, you
    can use the <function>var_dump</function> function.
   </para>
   <note>
    <para>
     The behaviour of an automatic conversion to array is currently
     undefined.
     <informalexample>
      <programlisting role="php">
$a = 1;       // $a is an integer
$a[0] = "f";  // $a becomes an array, with $a[0] holding "f"
      </programlisting>
     </informalexample>
    </para>
    <para>
     While the above example may seem like it should clearly result in
     $a becoming an array, the first element of which is 'f', consider
     this:
     <informalexample>
      <programlisting role="php">
$a = "1";     // $a is a string
$a[0] = "f";  // What about string offsets? What happens?
      </programlisting>
     </informalexample>
    </para>
    <para>
     Since PHP supports indexing into strings via offsets using the
     same syntax as array indexing, the example above leads to a
     problem: should $a become an array with its first element being
     "f", or should "f" become the first character of the string $a?
    </para>
    <para>
     For this reason, as of PHP 3.0.12 and PHP 4.0b3-RC4, the result
     of this automatic conversion is considered to be undefined. Fixes
     are, however, being discussed.
    </para>
   </note>

   <sect2 id="language.types.typecasting">
    <title>Type Casting</title>

    <para>
     Type casting in PHP works much as it does in C: the name of the
     desired type is written in parentheses before the variable which
     is to be cast.
     <informalexample>
      <programlisting role="php">
$foo = 10;   // $foo is an integer
$bar = (float) $foo;   // $bar is a float
      </programlisting>
     </informalexample>
    </para>
    <para>
     The casts allowed are:
     <itemizedlist>
      <listitem>
       <simpara>(int), (integer) - cast to integer</simpara>
      </listitem>
      <listitem>
       <simpara>(bool), (boolean) - cast to boolean</simpara>
      </listitem>
      <listitem>
       <simpara>(float), (double), (real) - cast to float</simpara>
      </listitem>
      <listitem>
       <simpara>(string) - cast to string</simpara>
      </listitem>
      <listitem>
       <simpara>(array) - cast to array</simpara>
      </listitem>
      <listitem>
       <simpara>(object) - cast to object</simpara>
      </listitem>
     </itemizedlist>
    </para>
    <note>
     <simpara>
      Instead of casting a variable to string, you can also enclose
      the variable in double quotes.
      <!-- TODO: example -->
     </simpara>
    </note>
     
    <para>
     Note that tabs and spaces are allowed inside the parentheses, so
     the following are functionally equivalent:
     <informalexample>
      <programlisting role="php">
$foo = (int) $bar;
$foo = ( int ) $bar;
      </programlisting>
     </informalexample>
    </para>
    <para>
     It may not be obvious exactly what will happen when casting
     between certain types. For more info, see these sections:
    
     <itemizedlist>
      <listitem>
       <simpara><link linkend="language.types.boolean.casting">Converting to 
        boolean</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.integer.casting">Converting to 
        integer</link></simpara>
      </listitem>
      <!-- don't exist yet
      <listitem>
       <simpara><link linkend="language.types.float.casting">Converting to 
        float</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.string.casting">Converting to 
        string</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.array.casting">Converting to 
        array</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.object.casting">Converting to 
        object</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.resource.casting">Converting to 
        resource</link></simpara>
      </listitem>
      <listitem>
       <simpara><link linkend="language.types.null.casting">Converting to 
        &null;</link></simpara>
      </listitem>
      -->
     </itemizedlist>
    
    </para>
    <para>
     <!-- TODO: move to 'converting to string' -->
     When casting or forcing a conversion from array to string, the
     result will be the word <literal>Array</literal>. When casting or
     forcing a conversion from object to string, the result will be
     the word <literal>Object</literal>. 
     
     <!-- not with my PHP, not even a notice... maybe in PHP3? 
     Does someone know? 
     
     In both cases a warning will
     be issued. -->
    </para>
    <para>
     When casting from a scalar or a string variable to an array, the
     variable will become the first element of the array:
     <informalexample>
      <programlisting role="php">
$var = 'ciao';
$arr = (array) $var;
echo $arr[0];  // outputs 'ciao'  
      </programlisting>
     </informalexample>
    </para>
    <para>
     When casting from a scalar or a string variable to an object, the
     variable will become an attribute of the object; the attribute
     name will be 'scalar':
     <informalexample>
      <programlisting role="php">
$var = 'ciao';
$obj = (object) $var;
echo $obj-&gt;scalar;  // outputs 'ciao'
      </programlisting>
     </informalexample>
    </para>

   </sect2>
  </sect1>

 </chapter>
 
<!-- 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:"../../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
-->