tal Thu Mar 21 07:07:56 2002 EDT
Added files:
/phpdoc/he/language types.xml
Log:
intial translation
Index: phpdoc/he/language/types.xml
+++ phpdoc/he/language/types.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!--EN-Revision: 1.73 Maintainer: tal Status: working -->
<chapter id="language.types">
<title>סוגי נתונים</title>
<sect1 id="language.types.intro">
<title>הקדמה</title>
<simpara>
PHP תומכת בשמונה סוגי נתונים.
<!-- (all types are primitive in php) -->
</simpara>
<para>
ארבעה סוגים סקלרים (בסיסיים, שלא ניתן לפצלם לחלקים):
<!-- (basic, can't be split into parts) --> types:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.boolean">בוליאני</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.integer">מספר שלם</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.float">מספר בעל נקודה צפה</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.string">מחרוזת</link>
</simpara>
</listitem>
</itemizedlist>
שני סוגים מורכבים:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.array">מערך</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.object">אובייקט</link>
</simpara>
</listitem>
</itemizedlist>
ולבסוף, שני סוגים מיוחדים:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.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
("<<<"). One should provide an identifier after
<literal><<<</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&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> => <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> => </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">
<?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->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
-->
