sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Major cleanup of language.types.*; mostly grammatical work, some markup and WS fixes, no new content. The title 'Resource' was changed to 'Resources' for consistency; a TOC regen is needed to reflect it.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@253468 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind 2008-02-21 18:43:17 +00:00
parent 2dd73402e4
commit 0feec568a3
11 changed files with 514 additions and 526 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
language/types.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.199 $ -->
<!-- $Revision: 1.200 $ -->
<chapter xml:id="language.types" xmlns="http://docbook.org/ns/docbook">
<title>Types</title>
@ -30,7 +30,7 @@
<listitem>
<simpara>
<type>float</type> (floating-point number, aka '<type>double</type>')
<type>float</type> (floating-point number, aka <type>double</type>)
</simpara>
</listitem>
@ -115,27 +115,27 @@
</para>
<simpara>
You may also find some references to the type "double". Consider double the
same as float, the two names exist only for historic reasons.
Some references to the type "double" may remain in the manual. Consider
double the same as float; the two names exist only for historic reasons.
</simpara>
<simpara>
The type of a variable is usually not set by the programmer; rather, it is
The type of a variable is not usually 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>.
To check the type and value of an
<link linkend="language.expressions">expression</link>, use the
<function>var_dump</function> function.
</simpara>
<para>
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
To get a human-readable representation of a type for debugging, use the
<function>gettype</function> function. To check for a certain type, do
<emphasis>not</emphasis> use <function>gettype</function>, but rather the
<literal>is_<replaceable>type</replaceable></literal> functions. Some
examples:
</para>
@ -169,18 +169,18 @@ if (is_string($a_bool)) {
</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.
To forcibly convert a variable to a certain type, 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 be evaluated with different values 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>. Also, you may be interested in viewing
<link linkend="types.comparisons">the type comparison tables</link>, as they
show examples of various type related comparisons.
Juggling</link>. <link linkend="types.comparisons">The type comparison
tables</link> may also be useful, as they show examples of various
type-related comparisons.
</simpara>
</sect1>

282
language/types/array.xml
View file

@ -1,21 +1,22 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml: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,
collection, stack, queue and probably more. Because you can have another PHP
array as a value, you can also quite easily simulate trees.
An <type>array</type> in PHP is actually an ordered map. A map is a type that
associates <emphasis>values</emphasis> to <emphasis>keys</emphasis>. This type
is optimized for several different uses; it can be treated as an array,
list (vector), hash table (an implementation of a map), dictionary,
collection, stack, queue, and probably more. As <type>array</type> values can
be other <type>array</type>s, trees and multidimensional <type>array</type>s
are also possible.
</para>
<para>
Explanation of those data structures is beyond the scope of this manual, but
you'll find at least one example for each of them. For more information we
refer you to external literature about this broad topic.
at least one example is provided for each of them. For more information, look
towards the considerable literature that exists about this broad topic.
</para>
<sect2 xml:id="language.types.array.syntax">
@ -26,18 +27,18 @@
<para>
An <type>array</type> can be created by the <function>array</function>
language-construct. It takes a certain number of comma-separated
language construct. It takes as parameters any number of comma-separated
<literal><replaceable>key</replaceable> =&gt;
<replaceable>value</replaceable></literal> pairs.
</para>
<synopsis>
array( <optional> <replaceable>key</replaceable> =&gt; </optional> <replaceable>value</replaceable>
, ...
)
// <replaceable>key</replaceable> may be an <type>integer</type> or <type>string</type>
// <replaceable>value</replaceable> may be any value
</synopsis>
, ...
)
// <replaceable>key</replaceable> may only be an <type>integer</type> or <type>string</type>
// <replaceable>value</replaceable> may be any value of any type</synopsis>
<!-- Do not fix the whitespace for the synopsis end element. A limitation of PhD prevents proper trimming -->
<informalexample>
<programlisting role="php">
@ -58,13 +59,14 @@ echo $arr[12]; // 1
<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>).
Floats in <varname>key</varname> are truncated to <type>integer</type>.
There are no different indexed and associative array types in PHP; there is
only one array type, which can both contain integer and string indices.
<type>Float</type>s in <varname>key</varname> are truncated to
<type>integer</type>. The indexed and associative <type>array</type> types
are the same type in PHP, which can both contain <type>integer</type> and
<type>string</type> indices.
</para>
<para>
A value can be of any PHP type.
A value can be any PHP type.
</para>
<informalexample>
@ -82,10 +84,10 @@ echo $arr["somearray"]["a"]; // 42
</informalexample>
<para>
If you do not specify a key for a given value, then the maximum of the
integer indices is taken, and the new key will be that maximum value + 1. If
you specify a key that already has a value assigned to it, that value will
be overwritten.
If a key is not specified for a value, the maximum of the
<type>integer</type> indices is taken and the new key will be that value
plus 1. If a key that already has an assigned value is specified, that value
will be overwritten.
</para>
<informalexample>
@ -104,55 +106,53 @@ array(5 => 43, 6 => 32, 7 => 56, "b" => 12);
<warning>
<simpara>
As of PHP 4.3.0, the index generation behaviour described above has
changed. Now, if you append to an array in which the current maximum key is
negative, then the next key created will be zero (<literal>0</literal>).
Before, the new index would have been set to the largest existing key + 1,
the same as positive indices are.
Before PHP 4.3.0, appending to an <type>array</type> in which the current
maximum key was negative would create a new key as described above. Since
PHP 4.3.0, the new key will be <literal>0</literal>.
</simpara>
</warning>
<para>
Using &true; as a key will evaluate to <type>integer</type>
<literal>1</literal> as key. Using &false; as a key will evaluate to
<type>integer</type> <literal>0</literal> as key. Using
<literal>NULL</literal> as a key will evaluate to the empty string. Using
the empty string as key will create (or overwrite) a key with the empty
string and its value; it is not the same as using empty brackets.
Using &true; as <varname>key</varname> will evaluate to <type>integer</type>
<literal>1</literal> as a key. Using &false; as <varname>key</varname> will
evaluate to <type>integer</type> <literal>0</literal> as a key. Using
&null; as a key will evaluate to the empty string. Using the empty string as
a key will create (or overwrite) a key with the empty string and its value;
it is <emphasis>not</emphasis> the same as using empty brackets.
</para>
<para>
You cannot use arrays or objects as keys. Doing so will result in a warning:
<literal>Illegal offset type</literal>.
<type>Array</type>s and <type>object</type>s can not be used as keys. Doing
so will result in a warning: <literal>Illegal offset type</literal>.
</para>
</sect3>
<sect3 xml:id="language.types.array.syntax.modifying">
<title>Creating/modifying with square-bracket syntax</title>
<title>Creating/modifying with square bracket syntax</title>
<para>
You can also modify an existing array by explicitly setting values in it.
An existing <type>array</type> can be modified by explicitly setting values
in it.
</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.
This is done by assigning values to the <type>array</type>, specifying the
key in brackets. The key can also be omitted, resulting in an empty pair of
brackets (<literal>[]</literal>).
</para>
<synopsis>
$arr[<replaceable>key</replaceable>] = <replaceable>value</replaceable>;
$arr[] = <replaceable>value</replaceable>;
// <replaceable>key</replaceable> may be an <type>integer</type> or <type>string</type>
// <replaceable>value</replaceable> may be any value
</synopsis>
// <replaceable>value</replaceable> may be any value of any type</synopsis>
<para>
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 an element specified with its key. If you want to
remove a key/value pair, you need to <function>unset</function> it.
If <varname>$arr</varname> doesn't exist yet, it will be created, so this is
also an alternative way to create an <type>array</type>. To change a certain
value, assign a new value to that element using its key. To remove a
key/value pair, call the <function>unset</function> function on it.
</para>
<informalexample>
@ -177,28 +177,18 @@ unset($arr); // This deletes the whole array
<note>
<para>
As mentioned above, if you provide the brackets with no key specified, then
the maximum of the existing integer indices is taken, and the new key will
be that maximum value + 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.
As mentioned above, if no key is specified, the maximum of the existing
<type>integer</type> indices is taken, and the new key will be that maximum
value plus 1. If no <type>integer</type> indices exist yet, the key will
be <literal>0</literal> (zero). If a key that already has a value is
specified, that value will be overwritten.
</para>
<warning>
<simpara>
As of PHP 4.3.0, the index generation behaviour described above has
changed. Now, if you append to an array in which the current maximum key
is negative, then the next key created will be zero
(<literal>0</literal>). Before, the new index would have been set to the
largest existing key + 1, the same as positive indices are.
</simpara>
</warning>
<para>
Note that the maximum integer key used for this <emphasis>need not
currently exist in the array</emphasis>. It simply must have existed in the
array at some time since the last time the array was re-indexed. The
following example illustrates:
currently exist in the <type>array</type></emphasis>. It need only have
existed in the <type>array</type> at some time since the last time the
<type>array</type> was re-indexed. The following example illustrates:
</para>
<informalexample>
@ -215,8 +205,7 @@ foreach ($array as $i => $value) {
}
print_r($array);
// Append an item (note that the new key is 5, instead of 0 as you
// might expect).
// Append an item (note that the new key is 5, instead of 0).
$array[] = 6;
print_r($array);
@ -269,10 +258,11 @@ Array
<note>
<para>
The <function>unset</function> function allows unsetting keys of an array.
Be aware that the array will NOT be reindexed. If you only use "usual
integer indices" (starting from zero, increasing by one), you can achieve
the reindex effect by using <function>array_values</function>.
The <function>unset</function> function allows removing keys from an
<type>array</type>. Be aware that the array will <emphasis>not</emphasis> be
reindexed. If a true "remove and shift" behavior is desired, the
<type>array</type> can be reindexed using the
<function>array_values</function> function.
</para>
<informalexample>
@ -297,8 +287,8 @@ $b = array_values($a);
<para>
The <link linkend="control-structures.foreach">foreach</link> control
structure exists specifically for arrays. It provides an easy way to traverse
an array.
structure exists specifically for <type>array</type>s. It provides an easy
way to traverse an <type>array</type>.
</para>
</sect2>
@ -309,9 +299,10 @@ $b = array_values($a);
<title>Why is <literal>$foo[bar]</literal> wrong?</title>
<para>
You should always use quotes around a string literal array index. For
example, use $foo['bar'] and not $foo[bar]. But why is $foo[bar] wrong? You
might have seen the following syntax in old scripts:
Always use quotes around a string literal array index. For example,
<literal>$foo['bar']</literal> is correct, while
<literal>$foo[bar]</literal> is not. But why? It is common to encounter this
kind of syntax in old scripts:
</para>
<informalexample>
@ -327,22 +318,21 @@ echo $foo[bar];
</informalexample>
<para>
This is wrong, but it works. Then, why is it wrong? The reason is that this
code has an undefined constant (bar) rather than a string ('bar' - notice
the quotes), and PHP may in future define constants which, unfortunately for
your code, have the same name. It works because PHP automatically converts
a <emphasis>bare string</emphasis> (an unquoted string which does not
correspond to any known symbol) into a string which contains the bare
string. For instance, if there is no defined constant named
<constant>bar</constant>, then PHP will substitute in the string
<literal>'bar'</literal> and use that.
This is wrong, but it works. The reason is that this code has an undefined
constant (bar) rather than a <type>string</type> ('bar' - notice the
quotes). PHP may in future define constants which, unfortunately for such
code, have the same name. It works because PHP automatically converts a
<emphasis>bare string</emphasis> (an unquoted <type>string</type> which does
not correspond to any known symbol) into a <type>string</type> which
contains the bare <type>string</type>. For instance, if there is no defined
constant named <constant>bar</constant>, then PHP will substitute in the
<type>string</type> <literal>'bar'</literal> and use that.
</para>
<note>
<simpara>
This does not mean to <emphasis>always</emphasis> quote the key. You do not
want to quote keys which are
<link linkend="language.constants">constants</link> or
This does not mean to <emphasis>always</emphasis> quote the key. Do not
quote keys which are <link linkend="language.constants">constants</link> or
<link linkend="language.variables">variables</link>, as this will prevent
PHP from interpreting them.
</simpara>
@ -391,14 +381,14 @@ Good: 2
</note>
<para>
More examples to demonstrate this fact:
More examples to demonstrate this behaviour:
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// Let's show all errors
// Show all errors
error_reporting(E_ALL);
$arr = array('fruit' => 'apple', 'veggie' => 'carrot');
@ -407,30 +397,30 @@ $arr = array('fruit' => 'apple', 'veggie' => 'carrot');
print $arr['fruit']; // apple
print $arr['veggie']; // carrot
// Incorrect. This works but also throws a PHP error of
// level E_NOTICE because of an undefined constant named fruit
// Incorrect. This works but also throws a PHP error of level E_NOTICE because
// of an undefined constant named fruit
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print $arr[fruit]; // apple
// Let's define a constant to demonstrate what's going on. We
// will assign value 'veggie' to a constant named fruit.
// This defines a constant to demonstrate what's going on. The value 'veggie'
// is assigned to a constant named fruit.
define('fruit', 'veggie');
// Notice the difference now
print $arr['fruit']; // apple
print $arr[fruit]; // carrot
// The following is okay as it's inside a string. Constants are not
// looked for within strings so no E_NOTICE error here
// The following is okay, as it's inside a string. Constants are not looked for
// within strings, so no E_NOTICE occurs here
print "Hello $arr[fruit]"; // Hello apple
// With one exception, braces surrounding arrays within strings
// allows constants to be looked for
// With one exception: braces surrounding arrays within strings allows constants
// to be interpreted
print "Hello {$arr[fruit]}"; // Hello carrot
print "Hello {$arr['fruit']}"; // Hello apple
// This will not work, results in a parse error such as:
// This will not work, and will result in a parse error, such as:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// This of course applies to using superglobals in strings as well
print "Hello $arr['fruit']";
@ -444,18 +434,19 @@ print "Hello " . $arr['fruit']; // Hello apple
</informalexample>
<para>
When you turn <function>error_reporting</function> up to show
<constant>E_NOTICE</constant> level errors (such as setting it to
<constant>E_ALL</constant>) then you will see these errors. By default,
<link linkend="ini.error-reporting">error_reporting</link> is turned down to
not show them.
When <link linkend="ini.error-reporting">error_reporting</link> is set to
show <constant>E_NOTICE</constant> level errors (by setting it to
<constant>E_ALL</constant>, for example), such uses will become immediately
visible. By default,
<link linkend="ini.error-reporting">error_reporting</link> is set not to
show notices.
</para>
<para>
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:
section, what's inside the square brackets ('<literal>[</literal>' and
'<literal>]</literal>') must be an expression. This means that code like
this works:
</para>
<informalexample>
@ -470,8 +461,7 @@ echo $arr[somefunc($bar)];
<para>
This is an example of using a function return value as the array index. PHP
also knows about constants, as you may have seen the <literal>E_*</literal>
ones before.
also knows about constants:
</para>
<informalexample>
@ -508,24 +498,14 @@ $error_descriptions[8] = "This is just an informal notice";
because <literal>E_ERROR</literal> equals <literal>1</literal>, etc.
</para>
<para>
As we already explained in the above examples, <literal>$foo[bar]</literal>
still works but is wrong. 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 xml:id="language.types.array.foo-bar.why">
<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, or you may introduce another constant into your
application, 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
constant or keyword, or a constant in other code may interfere. For
example, it is already wrong to use the words <literal>empty</literal> and
<literal>default</literal> this way, since they are
<link linkend="reserved">reserved keywords</link>.
</para>
@ -548,18 +528,21 @@ $error_descriptions[8] = "This is just an informal notice";
<para>
For any of the types: <type>integer</type>, <type>float</type>,
<type>string</type>, <type>boolean</type> and <type>resource</type>, if you
convert a value to an <type>array</type>, you get an array with one element
(with index 0), which is the scalar value you started with.
<type>string</type>, <type>boolean</type> and <type>resource</type>,
converting a value to an <type>array</type> results in an array with a single
element with index zero and the value of the scalar which was converted. In
other words, <literal>(array)$scalarValue</literal> is exactly the same as
<literal>array($scalarValue)</literal>.
</para>
<para>
If you convert an <type>object</type> to an array, you get the properties
(member variables) of that object as the array's elements. The keys are the
member variable names with a few notable exceptions: private variables have
the class name prepended to the variable name; protected variables have a '*'
prepended to the variable name. These prepended values have null bytes on
either side. This can result in some unexpected behaviour.
If an <type>object</type> is converted to an <type>array</type>, the result
is an <type>array</type> whose elements are the <type>object</type>'s
properties. The keys are the member variable names, with a few notable
exceptions: private variables have the class name prepended to the variable
name; protected variables have a '*' prepended to the variable name. These
prepended values have null bytes on either side. This can result in some
unexpected behaviour:
</para>
<informalexample>
@ -588,7 +571,8 @@ var_dump((array) new B());
</para>
<para>
If you convert a &null; value to an array, you get an empty array.
Converting &null; to an <type>array</type> results in an empty
<type>array</type>.
</para>
</sect2>
@ -596,8 +580,9 @@ var_dump((array) new B());
<title>Comparing</title>
<para>
It is possible to compare arrays by <function>array_diff</function> and by
<link linkend="language.operators.array">Array operators</link>.
It is possible to compare arrays with the <function>array_diff</function>
function and with
<link linkend="language.operators.array">array operators</link>.
</para>
</sect2>
@ -605,8 +590,7 @@ var_dump((array) new B());
<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.
The array type in PHP is very versatile. Here are some examples:
</para>
<informalexample>
@ -707,8 +691,8 @@ Do you like yellow?
</example>
<para>
Changing values of the array directly is possible since PHP 5 by passing them
as reference. Prior versions need workaround:
Changing the values of the <type>array</type> directly is possible since PHP
5 by passing them by reference. Before that, a workaround is necessary:
</para>
<example xml:id="language.types.array.examples.changeloop">
@ -790,10 +774,10 @@ closedir($handle);
</example>
<para>
Arrays are ordered. You can also change the order using various sorting
functions. See the <link linkend="ref.array">array functions</link> section
for more information. You can count the number of items in an array using the
<function>count</function> function.
<type>Array</type>s are ordered. The order can be changed using various
sorting functions. See the <link linkend="ref.array">array functions</link>
section for more information. The <function>count</function> function can be
used to count the number of items in an <type>array</type>.
</para>
<example>
@ -809,8 +793,9 @@ print_r($files);
</example>
<para>
Because the value of an array can be anything, it can also be another array.
This way you can make recursive and multi-dimensional arrays.
Because the value of an <type>array</type> can be anything, it can also be
another <type>array</type>. This enables the creation of recursive and
multi-dimensional <type>array</type>s.
</para>
<example>
@ -848,10 +833,11 @@ $juices["apple"]["green"] = "good";
</example>
<para>
You should be aware that array assignment always involves value copying. It
also means that the internal array pointer used by
<function>current</function> and similar functions is reset. You need to use
the reference operator to copy an array by reference.
<type>Array</type> assignment always involves value copying. It also means
that the internal <type>array</type> pointer used by
<function>current</function> and similar functions is reset. Use the
<link linkend="language.operators">reference operator</link> to copy an
<type>array</type> by reference.
</para>
<informalexample>

27
language/types/boolean.xml
View file

@ -1,24 +1,24 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml:id="language.types.boolean">
<title>Booleans</title>
<simpara>
This is the easiest type. A <type>boolean</type> expresses a truth value. It
This is the simplest 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.
The <type>boolean</type> type was introduced in PHP 4.
</simpara>
</note>
<sect2 xml: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.
To specify a <type>boolean</type> literal, use the keywords &true; or
&false;. Both are case-insensitive.
</para>
<informalexample>
@ -32,9 +32,8 @@ $foo = True; // assign the value TRUE to $foo
</informalexample>
<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
Typically, some kind of <link linkend="language.operators">operator</link>
which returns a <type>boolean</type> value, and the value is passed on to a
<link linkend="language.control-structures">control structure</link>.
</para>
@ -53,7 +52,7 @@ if ($show_separators == TRUE) {
echo "<hr>\n";
}
// ...because you can simply type
// ...because instead, this can be used:
if ($show_separators) {
echo "<hr>\n";
}
@ -67,11 +66,11 @@ if ($show_separators) {
<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.
To explicitly convert a value to <type>boolean</type>, use the
<literal>(bool)</literal> or <literal>(boolean)</literal> casts. However, in
most cases the cast is unncecessary, since a value will be automatically
converted if an operator, function or control structure requires a
<type>boolean</type> argument.
</simpara>
<simpara>

49
language/types/float.xml
View file

@ -1,11 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml: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:
Floating point numbers (also known as "floats", "doubles", or "real numbers")
can be specified using any of the following syntaxes:
</para>
<informalexample>
@ -29,14 +29,14 @@ $c = 7E-10;
<![CDATA[
LNUM [0-9]+
DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
]]>
</programlisting>
</informalexample>
<para>
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
a precision of roughly 14 decimal digits is a common value (the 64 bit IEEE
format).
</para>
@ -44,27 +44,27 @@ EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
<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
It is typical that simple decimal fractions like <literal>0.1</literal> or
<literal>0.7</literal> cannot be converted into their internal binary
counterparts without a small 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>.
return <literal>7</literal> instead of the expected <literal>8</literal>,
since the internal representation will be something like
<literal role="infdec">7.9</literal>.
</para>
<para>
This is related to the fact that it is impossible to exactly express some
This is due to the fact that it is impossible to 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>.
<literal role="infdec">0.3</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.
So never trust floating number results to the last digit, and never compare
floating point numbers for equality. If higher precision is necessary,
the <link linkend="ref.bc">arbitrary precision math functions</link> and
<link linkend="ref.gmp">gmp</link> functions are available.
</para>
</warning>
@ -72,13 +72,14 @@ EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
<title>Converting to float</title>
<para>
For information on when and how strings are converted to floats, see the
section titled <link linkend="language.types.string.conversion">String
conversion to numbers</link>. For values of other types, the conversion is
the same as if the value would have been converted to integer and then to
float. See the <link linkend="language.types.integer.casting">Converting to
integer</link> section for more information. As of PHP 5, notice is thrown if
you try to convert object to float.
For information on converting <type>string</type>s to <type>float</type>, see
<link linkend="language.types.string.conversion">String conversion to
numbers</link>. For values of other types, the conversion is performed by
converting the value to <type>integer</type> first and then to
<type>float</type>. See
<link linkend="language.types.integer.casting">Converting to integer</link>
for more information. As of PHP 5, a notice is thrown if an
<type>object</type> is converted to <type>float</type>.
</para>
</sect2>

112
language/types/integer.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml:id="language.types.integer">
<title>Integers</title>
@ -10,23 +10,38 @@
<para>
See also:
<link linkend="ref.gmp">Arbitrary length integer / GMP</link>,
<link linkend="language.types.float">Floating point numbers</link>, and
<link linkend="ref.bc">Arbitrary precision / BCMath</link>
</para>
<itemizedlist>
<listitem>
<simpara>
<link linkend="ref.gmp">Arbitrary length integer / GMP</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.float">Floating point numbers</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="ref.bc">Arbitrary precision / BCMath</link>
</simpara>
</listitem>
</itemizedlist>
<sect2 xml: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 +).
<type>Integer</type>s can be specified in decimal (base 10), hexadecimal
(base 16), or octal (base 8) 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>.
To use octal notation, precede the number with a <literal>0</literal> (zero).
To use hexadecimal notation precede the number with <literal>0x</literal>.
</para>
<example>
@ -44,7 +59,7 @@ $a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
</example>
<para>
Formally the possible structure for integer literals is:
Formally, the structure for <type>integer</type> literals is:
</para>
<informalexample>
@ -65,17 +80,18 @@ integer : [+-]?decimal
</informalexample>
<para>
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. Integer size can be determined from
<constant>PHP_INT_SIZE</constant>, maximum value from
<constant>PHP_INT_MAX</constant> since PHP 4.4.0 and PHP 5.0.5.
The size of an <type>integer</type> 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 <type>integer</type>s. <type>Integer</type> size
can be determined using the constant <constant>PHP_INT_SIZE</constant>, and
maximum value using the constant <constant>PHP_INT_MAX</constant> since
PHP 4.4.0 and PHP 5.0.5.
</para>
<warning>
<para>
If an invalid digit is passed to octal integer (i.e. 8 or 9), the rest of
the number is ignored.
If an invalid digit is given in an octal <type>integer</type> (i.e. 8 or 9),
the rest of the number is ignored.
</para>
<example>
@ -95,10 +111,10 @@ var_dump(01090); // 010 octal = 8 decimal
<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.
If PHP encounters a number beyond the bounds of the <type>integer</type>
type, it will be interpreted as a <type>float</type> instead. Also, an
operation which results in a number beyond the bounds of the
<type>integer</type> type will return a <type>float</type> instead.
</para>
<informalexample>
@ -132,23 +148,22 @@ var_dump($large_number);
<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.
Unfortunately, there was a bug in PHP which caused this to not always work
correctly when negative numbers were involved. For example, the result of
<literal>-50000 * $million</literal> is <literal>-429496728</literal>.
However, when both operands were positive, there was no problem.
</simpara>
<simpara>
This is solved in PHP 4.1.0.
This was fixed in PHP 4.1.0.
</simpara>
</warning>
<para>
There is no integer division operator in PHP. <literal>1/2</literal> yields
the <type>float</type> <literal>0.5</literal>. You can cast the value to an
integer to always round it downwards, or you can use the
<function>round</function> function.
There is no <type>integer</type> division operator in PHP.
<literal>1/2</literal> yields the <type>float</type> <literal>0.5</literal>.
The value can be casted to an <type>integer</type> to round it downwards, or
the <function>round</function> function provides finer control over rounding.
</para>
<informalexample>
@ -169,15 +184,15 @@ var_dump(round(25/7)); // float(4)
<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 an <type>integer</type> argument. You can also convert a value to
integer with the function <function>intval</function>.
<literal>(int)</literal> or <literal>(integer)</literal> casts. However, in
most cases the cast is not needed, since a value will be automatically
converted if an operator, function or control structure requires an
<type>integer</type> argument. A value can also be converted to
<type>integer</type> with the <function>intval</function> function.
</simpara>
<simpara>
See also <link linkend="language.types.type-juggling">type-juggling</link>.
See also: <link linkend="language.types.type-juggling">type-juggling</link>.
</simpara>
<sect3 xml:id="language.types.integer.casting.from-boolean">
@ -195,15 +210,16 @@ var_dump(round(25/7)); // float(4)
</title>
<simpara>
When converting from float to integer, the number will be rounded
<emphasis>towards zero</emphasis>.
When converting from <type>float</type> to <type>integer</type>, the number
will be rounded <emphasis>towards zero</emphasis>.
</simpara>
<para>
If the float is beyond the boundaries of integer (usually
If the float is beyond the boundaries of <type>integer</type> (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!
<type>float</type> doesn't have enough precision to give an exact
<type>integer</type> result. No warning, not even a notice will be issued
when this happens!
</para>
<warning>
@ -223,8 +239,8 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
</informalexample>
<para>
See for more information the <link linkend="warn.float-precision">warning
about float-precision</link>.
See also the <link linkend="warn.float-precision">warning about float
precision</link>.
</para>
</warning>
</sect3>
@ -243,11 +259,9 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
<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> rely on this behaviour, as it can
change without notice.
The behaviour of converting to <type>integer</type> is undefined for other
types. Do <emphasis>not</emphasis> rely on any observed behaviour, as it
can change without notice.
</simpara>
</caution>
</sect3>

17
language/types/null.xml
View file

@ -1,21 +1,21 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml: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>.
The special &null; value represents a variable with no value. &null; is the
only possible value of type <type>NULL</type>.
</para>
<note>
<simpara>
The null type was introduced in PHP 4.
The <type>null</type> type was introduced in PHP 4.
</simpara>
</note>
<para>
A variable is considered to be &null; if
A variable is considered to be <type>null</type> if:
</para>
<itemizedlist>
@ -40,8 +40,8 @@
<title>Syntax</title>
<para>
There is only one value of type &null;, and that is the case-insensitive
keyword &null;.
There is only one value of type <type>null</type>, and that is the
case-insensitive keyword &null;.
</para>
<informalexample>
@ -55,7 +55,8 @@ $var = NULL;
</informalexample>
<para>
See also <function>is_null</function> and <function>unset</function>.
See also the functions <function>is_null</function> and
<function>unset</function>.
</para>
</sect2>

24
language/types/object.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml:id="language.types.object">
<title>Objects</title>
@ -7,8 +7,8 @@
<title>Object Initialization</title>
<para>
To initialize an object, you use the <literal>new</literal> statement to
instantiate the object to a variable.
To create a new <type>object</type>, use the <literal>new</literal> statement
to instantiate a class:
</para>
<informalexample>
@ -31,8 +31,8 @@ $bar->do_foo();
</informalexample>
<simpara>
For a full discussion, please read the section
<link linkend="language.oop">Classes and Objects</link>.
For a full discussion, see the
<link linkend="language.oop">Classes and Objects</link> chapter.
</simpara>
</sect2>
@ -41,13 +41,13 @@ $bar->do_foo();
<title>Converting to object</title>
<para>
If an object is converted to an object, it is not modified. If a value of any
other type is converted to an object, a new instance of the
<literal>stdClass</literal> built in class is created. If the value was
&null;, the new instance will be empty. Array converts to an object with
properties named by array keys and with corresponding values. For any other
value, a member variable named <literal>scalar</literal> will contain the
value.
If an <type>object</type> is converted to an <type>object</type>, it is not
modified. If a value of any other type is converted to an
<type>object</type>, a new instance of the <literal>stdClass</literal>
built-in class is created. If the value was &null;, the new instance will be
empty. <type>Array</type>s convert to an <type>object</type> with properties
named by keys, and corresponding values. For any other value, a member
variable named <literal>scalar</literal> will contain the value.
</para>
<informalexample>

39
language/types/pseudo-types.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<sect1 xml:id="language.pseudo-types">
<title>Pseudo-types and variables used in this documentation</title>
@ -13,7 +13,8 @@
<para>
<function>gettype</function> for example will accept all PHP types, while
<function>str_replace</function> will accept strings and arrays.
<function>str_replace</function> will accept <type>string</type>s and
<type>array</type>s.
</para>
</sect2>
@ -33,35 +34,36 @@
<para>
Some functions like <function>call_user_func</function> or
<function>usort</function> accept user defined callback functions as a
parameter. Callback functions can not only be simple functions but also
object methods including static class methods.
<function>usort</function> accept user-defined callback functions as a
parameter. Callback functions can not only be simple functions, but also
<type>object</type> methods, including static class methods.
</para>
<para>
A PHP function is simply passed by its name as a string. You can pass any
built-in or user defined function. Note that language constructs like
A PHP function is passed by its name as a <type>string</type>. Any built-in
or user-defined function can be used, except language constructs such as:
<function>array</function>, <function>echo</function>,
<function>empty</function>, <function>eval</function>,
<function>exit</function>, <function>isset</function>,
<function>list</function>, <function>print</function> or
<function>unset</function> cannot be called using a callback.
<function>unset</function>.
</para>
<para>
A method of an instantiated object is passed as an array containing an object
as the element with index 0 and a method name as the element with index 1.
A method of an instantiated <type>object</type> is passed as an
<type>array</type> containing an <type>object</type> at index 0 and the
method name at index 1.
</para>
<para>
Static class methods can also be passed without instantiating an object of
that class by passing the class name instead of an object as the element with
index 0.
Static class methods can also be passed without instantiating an
<type>object</type> of that class by passing the class name instead of an
<type>object</type> at index 0.
</para>
<para>
Apart from common user-defined function, <function>create_function</function>
can be used to create an anonymous callback function.
can also be used to create an anonymous callback function.
</para>
<example>
@ -118,8 +120,9 @@ call_user_func(array('B', 'parent::who')); // A
<note>
<simpara>
In PHP4, you will have to use a reference to create a callback that points
to the actual object, and not a copy of it. For more details, see
In PHP4, it was necessary to use a reference to create a callback that
points to the actual <type>object</type>, and not a copy of it. For more
details, see
<link linkend="language.references">References Explained</link>.
</simpara>
</note>
@ -130,8 +133,8 @@ call_user_func(array('B', 'parent::who')); // A
<title>void</title>
<para>
<literal>void</literal> in return type means that the return value is
useless. <literal>void</literal> in parameters list means that the function
<literal>void</literal> as a return type means that the return value is
useless. <literal>void</literal> in a parameter list means that the function
doesn't accept any parameters.
</para>

37
language/types/resource.xml
View file

@ -1,32 +1,32 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml:id="language.types.resource">
<title>Resource</title>
<title>Resources</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.
A <type>resource</type> 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 <type>resource</type> types.
</para>
<note>
<simpara>
The resource type was introduced in PHP 4
The <type>resource</type> type was introduced in PHP 4
</simpara>
</note>
<para>
See also <function>get_resource_type</function>.
See also the <function>get_resource_type</function> function.
</para>
<sect2 xml:id="language.types.resource.casting">
<title>Converting to resource</title>
<para>
As resource types hold special handlers to opened files, database
connections, image canvas areas and the like, you cannot convert any value to
a resource.
As <type>resource</type> variables hold special handlers to opened files,
database connections, image canvas areas and the like, converting to a
<type>resource</type> makes no sense.
</para>
</sect2>
@ -34,19 +34,18 @@
<title>Freeing resources</title>
<para>
Due to the reference-counting system introduced with PHP 4'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.
Thanks to the reference-counting system introduced with PHP 4's Zend Engine,
a <type>resource</type> with no more references to it is detected
automatically, and it is freed by the garbage collector. For this reason, it
is rarely necessary to free the memory manually.
</para>
<note>
<simpara>
Persistent database links are special, they are <emphasis>not</emphasis>
destroyed by the garbage collector. See also the section about
Persistent database links are an exception to this rule. They are
<emphasis>not</emphasis> destroyed by the garbage collector. See the
<link linkend="features.persistent-connections">persistent
connections</link>.
connections</link> section for more information.
</simpara>
</note>

348
language/types/string.xml
View file

@ -1,21 +1,21 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<sect1 xml: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. See
A <type>string</type> is series of characters. Before PHP 6, 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. See
<function>utf8_encode</function> and <function>utf8_decode</function> for some
Unicode support.
basic Unicode functionality.
</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.
It is no problem for a <type>string</type> to become very large. PHP imposes
no boundary on the size of a <type>string</type>; the only limit is the
available memory of the computer on which PHP is running.
</simpara>
</note>
@ -23,7 +23,7 @@
<title>Syntax</title>
<para>
A string literal can be specified in three different ways.
A <type>string</type> literal can be specified in three different ways:
</para>
<itemizedlist>
@ -48,17 +48,16 @@
<title>Single quoted</title>
<para>
The easiest way to specify a simple string is to enclose it in single quotes
(the character <literal>'</literal>).
The simplest way to specify a <type>string</type> 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 will also be printed! So usually there is no need to escape
the backslash itself.
To specify a literal single quote, escape it with a backslash
(<literal>\</literal>). To specify a literal backslash before a single
quote, or at the end of the <type>string</type>, double it
(<literal>\\</literal>). Note that attempting to escape any other character
will print the backslash too.
</para>
<note>
@ -66,7 +65,7 @@
Unlike the two other syntaxes,
<link linkend="language.variables">variables</link> and escape sequences
for special characters will <emphasis>not</emphasis> be expanded when they
occur in single quoted strings.
occur in single quoted <type>string</type>s.
</simpara>
</note>
@ -105,8 +104,8 @@ echo 'Variables do not $expand $either';
<title>Double quoted</title>
<para>
If the string is enclosed in double-quotes ("), PHP understands more escape
sequences for special characters:
If the <type>string</type> is enclosed in double-quotes ("), PHP will
interpret more escape sequences for special characters:
</para>
<table>
@ -115,8 +114,8 @@ echo 'Variables do not $expand $either';
<tgroup cols="2">
<thead>
<row>
<entry>sequence</entry>
<entry>meaning</entry>
<entry>Sequence</entry>
<entry>Meaning</entry>
</row>
</thead>
@ -172,14 +171,14 @@ echo 'Variables do not $expand $either';
</table>
<para>
Again, if you try to escape any other character, the backslash will be
printed too! Before PHP 5.1.1, backslash in <literal>\{$var}</literal>
hasn't been printed.
As in single quoted <type>string</type>s, escaping any other character will
result in the backslash being printed too. Before PHP 5.1.1, the backslash
in <literal>\{$var}</literal> was not been printed.
</para>
<para>
But the most important feature of double-quoted strings is the fact that
variable names will be expanded. See
The most important feature of double-quoted <type>string</type>s is the fact
that variable names will be expanded. See
<link linkend="language.types.string.parsing">string parsing</link> for
details.
</para>
@ -189,44 +188,44 @@ echo 'Variables do not $expand $either';
<title>Heredoc</title>
<simpara>
Another way to delimit strings is by using heredoc syntax ("&lt;&lt;&lt;").
One should provide an identifier (followed by new line) after
<literal>&lt;&lt;&lt;</literal>, then the string, and then the same
identifier to close the quotation.
A third way to delimit <type>string</type>s is the heredoc syntax:
<literal>&lt;&lt;&lt;</literal>. After this operator, an identifier is
provided, then a newline. The <type>string</type> itself follows, and then
the same identifier again 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
of the line. Also, the identifier 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
It is very important to note that the line with the closing identifier must
contain 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. It's also important to realize that
or tabs before or after the semicolon. It's also important to realize that
the first character before the closing identifier must be a newline as
defined by your operating system. This is <literal>\r</literal> on
Macintosh for example. Closing delimiter (possibly followed by a semicolon)
must be followed by a newline too.
defined by the local operating system. This is <literal>\n</literal> on
UNIX systems, including Mac OS X. The closing delimiter (possibly followed
by a semicolon) must also be followed by a newline.
</simpara>
<simpara>
If this rule is broken and the closing identifier is not "clean" then it's
not considered to be a closing identifier and PHP will continue looking for
one. If in this case a proper closing identifier is not found then a parse
error will result with the line number being at the end of the script.
If this rule is broken and the closing identifier is not "clean", it will
not be considered a closing identifier, and PHP will continue looking for
one. If a proper closing identifier is not found before the end of the
current file, a parse error will result at the last line.
</simpara>
<para>
It is not allowed to use heredoc syntax in initializing class members. Use
other string syntaxes instead.
Heredocs can not be used for initializing class members. Use other
<type>string</type> syntaxes instead.
</para>
<example>
<title>Invalid example</title>
<programlisting role="php">
@ -244,11 +243,11 @@ EOT;
</warning>
<para>
Heredoc 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
Heredoc text behaves just like a double-quoted <type>string</type>, without
the double quotes. This means that quotes in a heredoc do not need to be
escaped, but the escape codes listed above can still be used. Variables are
expanded, but the same care must be taken when expressing complex variables
inside a heredoc as with strings.
inside a heredoc as with <type>string</type>s.
</para>
<example>
@ -293,23 +292,24 @@ EOT;
Heredoc support was added in PHP 4.
</para>
</note>
</sect3>
<sect3 xml:id="language.types.string.parsing">
<title>Variable parsing</title>
<simpara>
When a string is specified in double quotes or with heredoc,
When a <type>string</type> is specified in double quotes or with heredoc,
<link linkend="language.variables">variables</link> 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.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 <type>array</type> value, or an <type>object</type>
property.
embed a variable, an <type>array</type> value, or an <type>object</type>
property in a <type>string</type> with a minimum of effort.
</simpara>
<simpara>
@ -323,8 +323,8 @@ EOT;
<simpara>
If a dollar sign (<literal>$</literal>) is encountered, the parser will
greedily take as many 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.
Enclose the variable name in curly braces to explicitly specify the end of
the name.
</simpara>
<informalexample>
@ -332,8 +332,8 @@ EOT;
<![CDATA[
<?php
$beer = 'Heineken';
echo "$beer's taste is great"; // works, "'" is an invalid character for varnames
echo "He drank some $beers"; // won't work, 's' is a valid character for varnames
echo "$beer's taste is great"; // works; "'" is an invalid character for variable names
echo "He drank some $beers"; // won't work; 's' is a valid character for variable names
echo "He drank some ${beer}s"; // works
echo "He drank some {$beer}s"; // works
?>
@ -342,16 +342,10 @@ echo "He drank some {$beer}s"; // works
</informalexample>
<simpara>
Similarly, you can also have an <type>array</type> index or an
<type>object</type> 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.
-->
Similarly, an <type>array</type> index or an <type>object</type> property
can be parsed. With array indices, the closing square bracket
(<literal>]</literal>) marks the end of the index. The same rules apply to
object properties as to simple variables.
</simpara>
<informalexample>
@ -359,22 +353,21 @@ echo "He drank some {$beer}s"; // works
<![CDATA[
<?php
// These examples are specific to using arrays inside of strings.
// When outside of a string, always quote your array string keys
// and do not use {braces} when outside of strings either.
// When outside of a string, always quote array string keys and do not use
// {braces}.
// Let's show all errors
// Show all errors
error_reporting(E_ALL);
$fruits = array('strawberry' => 'red', 'banana' => 'yellow');
// Works but note that this works differently outside string-quotes
// Works, but note that this works differently outside a string
echo "A banana is $fruits[banana].";
// Works
echo "A banana is {$fruits['banana']}.";
// Works but PHP looks for a constant named banana first
// as described below.
// Works, but PHP looks for a constant named banana first, as described below.
echo "A banana is {$fruits[banana]}.";
// Won't work, use braces. This results in a parse error.
@ -408,24 +401,26 @@ echo "This square is $square->{width}00 centimeters broad.";
<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.
This isn't called complex because the syntax is complex, but because it
allows for the use of complex expressions.
</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 "{\$" to get a literal "{$"). Some examples to make
it clear:
In fact, any value in the namespace can be included in a
<type>string</type> with this syntax. Simply write the expression the same
way as it would appeared outside the <type>string</type>, and then wrap it
in <literal>{</literal> and <literal>}</literal>. Since
<literal>{</literal> can not be escaped, this syntax will only be
recognised when the <literal>$</literal> immediately follows the
<literal>{</literal>. Use <literal>{\$</literal> to get a literal
<literal>{$</literal>. Some examples to make it clear:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// Let's show all errors
// Show all errors
error_reporting(E_ALL);
$great = 'fantastic';
@ -443,20 +438,20 @@ echo "This square is {$square->width}00 centimeters broad.";
// Works
echo "This works: {$arr[4][3]}";
// This is wrong for the same reason as $foo[bar] is wrong
// outside a string. In other words, it will still work but
// because PHP first looks for a constant named foo, it will
// throw an error of level E_NOTICE (undefined constant).
// This is wrong for the same reason as $foo[bar] is wrong outside a string.
// In other words, it will still work, but only because PHP first looks for a
// constant named foo; an error of level E_NOTICE (undefined constant) will be
// thrown.
echo "This is wrong: {$arr[foo][3]}";
// Works. When using multi-dimensional arrays, always use
// braces around arrays when inside of strings
// Works. When using multi-dimensional arrays, always use braces around arrays
// when inside of strings
echo "This works: {$arr['foo'][3]}";
// Works.
echo "This works: " . $arr['foo'][3];
echo "You can even write {$obj->values[3]->name}";
echo "This works too: {$obj->values[3]->name}";
echo "This is the value of the var named $name: {${$name}}";
@ -476,16 +471,7 @@ echo "I'd like to have another {${ strrev('reeb') }}, hips";
<note>
<para>
Functions and method calls inside <literal>{$ }</literal> work since PHP 5.
</para>
</note>
<note>
<para>
Parsing variables within strings uses more memory than string
concatenation. When writing a PHP script in which memory usage is a
concern, consider using the concatenation operator (.) rather than
variable parsing.
Functions and method calls inside <literal>{$}</literal> work since PHP 5.
</para>
</note>
@ -496,17 +482,18 @@ echo "I'd like to have another {${ strrev('reeb') }}, hips";
<title>String access and modification by character</title>
<para>
Characters within strings may be accessed and modified by specifying the
zero-based offset of the desired character after the string using square
array-brackets like <varname>$str[42]</varname> so think of a string as an
<type>array</type> of characters.
Characters within <type>string</type>s may be accessed and modified by
specifying the zero-based offset of the desired character after the
<type>string</type> using square <type>array</type> brackets, as in
<varname>$str[42]</varname>. Think of a <type>string</type> as an
<type>array</type> of characters for this purpose.
</para>
<note>
<simpara>
They may also be accessed using braces like <varname>$str{42}</varname> for
the same purpose. However, using square array-brackets is preferred because
the {braces} style is deprecated as of PHP 6.
<type>String</type>s may also be accessed using braces, as in
<varname>$str{42}</varname>, for the same purpose. However, this syntax is
deprecated as of PHP 6. Use square brackets instead.
</simpara>
</note>
@ -530,9 +517,6 @@ $last = $str[strlen($str)-1];
$str = 'Look at the sea';
$str[strlen($str)-1] = 'e';
// Alternative method using {} is deprecated as of PHP 6
$third = $str{2};
?>
]]>
</programlisting>
@ -540,8 +524,8 @@ $third = $str{2};
<note>
<para>
Accessing by <literal>[]</literal> or <literal>{}</literal> to
variables of other type silently returns &null;.
Accessing variables of other types using <literal>[]</literal> or
<literal>{}</literal> silently returns &null;.
</para>
</note>
@ -552,33 +536,33 @@ $third = $str{2};
<title>Useful functions and operators</title>
<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.
<type>String</type>s may be concatenated using the '.' (dot) operator. Note
that the '+' (addition) operator will <emphasis>not</emphasis> work for this.
See <link linkend="language.operators.string">String operators</link> for
more information.
</para>
<para>
There are a lot of useful functions for string modification.
There are a number of useful functions for <type>string</type> manipulation.
</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>).
general functions, and the <link linkend="ref.regex">regular expression
functions</link> or the <link linkend="ref.pcre">Perl-compatible regular
expression functions</link> for advanced find &amp; replace functionality.
</simpara>
<simpara>
There are also <link linkend="ref.url">functions for URL-strings</link>, and
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>.
Finally, see also the <link linkend="ref.ctype">character type
functions</link>.
</simpara>
</sect2>
@ -586,62 +570,63 @@ $third = $str{2};
<title>Converting to string</title>
<para>
You can convert a value to a string using the <literal>(string)</literal>
cast, or the <function>strval</function> function. String conversion is
automatically done in the scope of an expression for you where a string is
needed. This happens when you use the <function>echo</function> or
<function>print</function> functions, or when you compare a variable value to
a string. Reading the manual sections on
A value can be converted to a <type>string</type> using the
<literal>(string)</literal> cast or the <function>strval</function> function.
<type>String</type> conversion is automatically done in the scope of an
expression where a <type>string</type> is needed. This happens when using the
<function>echo</function> or <function>print</function> functions, or when a
variable is compared to a <type>string</type>. The sections on
<link linkend="language.types">Types</link> and
<link linkend="language.types.type-juggling">Type Juggling</link> will make
the following clearer. See also <function>settype</function>.
the following clearer. See also the <function>settype</function> function.
</para>
<para>
A <type>boolean</type> &true; value is converted to the string
<literal>"1"</literal>, the &false; value is represented as
<literal>""</literal> (empty string). This way you can convert back and forth
between boolean and string values.
A <type>boolean</type> &true; value is converted to the <type>string</type>
<literal>"1"</literal>. <type>Boolean</type> &false; is converted to
<literal>""</literal> (the empty string). This allows conversion back and
forth between <type>boolean</type> and <type>string</type> values.
</para>
<para>
An <type>integer</type> or a floating point number (<type>float</type>) is
converted to a string representing the number with its digits (including the
exponent part for floating point numbers). Floating point numbers can be
converted using the exponential notation (<literal>4.1E+6</literal>).
An <type>integer</type> or <type>float</type> is converted to a
<type>string</type> representing the number textually (including the
exponent part for <type>float</type>s). Floating point numbers can be
converted using exponential notation (<literal>4.1E+6</literal>).
</para>
<note>
<para>
The decimal point character is defined in the script's locale (category
LC_NUMERIC). See <function>setlocale</function>.
LC_NUMERIC). See the <function>setlocale</function> function.
</para>
</note>
<para>
Arrays are always converted to the string <literal>"Array"</literal>, so you
cannot dump out the contents of an <type>array</type> with
<function>echo</function> or <function>print</function> to see what is inside
them. To view one element, you'd do something like
<literal>echo $arr['foo']</literal>. See below for tips on dumping/viewing
the entire contents.
<type>Array</type>s are always converted to the <type>string</type>
<literal>"Array"</literal>; because of this, <function>echo</function> and
<function>print</function> can not by themselves show the contents of an
<type>array</type>. To view a single element, use a construction such as
<literal>echo $arr['foo']</literal>. See below for tips on viewing the entire
contents.
</para>
<para>
Objects in PHP 4 are always converted to the string
<literal>"Object"</literal>. If you would like to print out the member
variable values of an <type>object</type> for debugging reasons, read the
paragraphs below. If you would like to find out the class name of which an
object is an instance of, use <function>get_class</function>. As of PHP 5,
__toString() method is used if applicable.
<type>Object</type>s in PHP 4 are always converted to the <type>string</type>
<literal>"Object"</literal>. To print the values of object members for
debugging reasons, read the paragraphs below. To get an object's class name,
use the <function>get_class</function> function. As of PHP 5, the
<link linkend="language.oop5.magic">__toString</link> method is used when
applicable.
</para>
<para>
Resources are always converted to strings with the structure
<literal>"Resource id #1"</literal> where <literal>1</literal> is the unique
number of the <type>resource</type> assigned by PHP during runtime. If you
would like to get the type of the resource, use
<function>get_resource_type</function>.
<type>Resource</type>s are always converted to <type>string</type>s with the
structure <literal>"Resource id #1"</literal>, where <literal>1</literal> is
the unique number assigned to the <type>resource</type> by PHP at runtime. Do
not rely upon this structure; it is subject to change. To get a
<type>resource</type>'s type, use the
<function>get_resource_type</function> function.
</para>
<para>
@ -649,40 +634,44 @@ $third = $str{2};
</para>
<para>
As you can see above, printing out the arrays, objects or resources does not
provide you any useful information about the values themselves. Look at the
As stated above, directly converting an <type>array</type>,
<type>object</type>, or <type>resource</type> to a <type>string</type> does
not provide any useful information about the value beyond its type. See the
functions <function>print_r</function> and <function>var_dump</function> for
better ways to print out values for debugging.
more effective means of inspecting the contents of these types.
</para>
<para>
You can also convert PHP values to strings to store them permanently. This
method is called serialization, and can be done with the function
<function>serialize</function>. You can also serialize PHP values to XML
structures, if you have <link linkend="ref.wddx">WDDX</link> support in your
PHP setup.
Most PHP values can also be converted to <type>string</type>s for permanent
storage. This method is called serialization, and is performed by the
<function>serialize</function> function. If the PHP engine was built with
<link linkend="ref.wddx">WDDX</link> support, PHP values can also be
serialized as well-formed XML text.
</para>
</sect2>
<sect2 xml:id="language.types.string.conversion">
<title>String conversion to numbers</title>
<simpara>
When a string is evaluated as a numeric value, the resulting value and type
are determined as follows.
When a <type>string</type> is evaluated in a numeric context, 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.
The <type>string</type> will be evaluated as a <type>float</type> if it
contains any of the characters '.', 'e', or 'E'. Otherwise, it will be
evaluated as an <type>integer</type>.
</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.
The value is given by the initial portion of the <type>string</type>. If the
<type>string</type> 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>
<informalexample>
@ -708,9 +697,8 @@ $foo = "10.0 pigs " + 1.0; // $foo is float (11)
</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:
To test any of the examples in this section, cut and paste the examples and
insert the following line to see what's going on:
</para>
<informalexample>
@ -724,10 +712,10 @@ echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
</informalexample>
<para>
Do not expect to get the code of one character by converting it to integer
(as you would do in C for example). Use the functions
<function>ord</function> and <function>chr</function> to convert between
charcodes and characters.
Do not expect to get the code of one character by converting it to integer,
as is done in C. Use the <function>ord</function> and
<function>chr</function> functions to convert between ASCII codes and
characters.
</para>
</sect2>

71
language/types/type-juggling.xml
View file

@ -1,24 +1,25 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<sect1 xml: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.
declaration; a variable's type is determined by the context in which the
variable is used. That is to say, if a <type>string</type> value is assigned
to variable <varname>$var</varname>, <varname>$var</varname> becomes a
<type>string</type>. If an <type>integer</type> value is then assigned to
<varname>$var</varname>, it becomes an <type>integer</type>.
</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
If either operand is a <type>float</type>, then both operands are evaluated as
<type>float</type>s, and the result will be a <type>float</type>. Otherwise,
the operands will be interpreted as <type>integer</type>s, and the result will
also be an <type>integer</type>. Note that this does <emphasis>not</emphasis>
change the types of the operands themselves; the only change is in how the
operands are evaluated.
operands are evaluated and what the type of the expression itself is.
</para>
<informalexample>
@ -61,24 +62,26 @@ examples:
</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>.
To force a variable to be evaluated as a certain type, see the section on
<link linkend="language.types.typecasting">Type casting</link>. To change the
type of a variable, see the <function>settype</function> 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.
To test any of the examples in this section, use the
<function>var_dump</function> function.
</para>
<note>
<para>
The behaviour of an automatic conversion to array is currently undefined.
The behaviour of an automatic conversion to <type>array</type> is currently
undefined.
</para>
<para>
Also, because PHP supports indexing into strings via offsets using the same
syntax as array indexing, the following example holds true for all PHP
versions:
Also, because PHP supports indexing into <type>string</type>s via offsets
using the same syntax as <type>array</type> indexing, the following example
holds true for all PHP versions:
</para>
<informalexample>
@ -124,25 +127,25 @@ $bar = (boolean) $foo; // $bar is a boolean
<itemizedlist>
<listitem>
<simpara>(int), (integer) - cast to integer</simpara>
<simpara>(int), (integer) - cast to <type>integer</type></simpara>
</listitem>
<listitem>
<simpara>(bool), (boolean) - cast to boolean</simpara>
<simpara>(bool), (boolean) - cast to <type>boolean</type></simpara>
</listitem>
<listitem>
<simpara>(float), (double), (real) - cast to float</simpara>
<simpara>(float), (double), (real) - cast to <type>float</type></simpara>
</listitem>
<listitem>
<simpara>(string) - cast to string</simpara>
<simpara>(string) - cast to <type>string</type></simpara>
</listitem>
<listitem>
<simpara>(binary) - cast to binary string (PHP 6)</simpara>
<simpara>(binary) - cast to binary <type>string</type> (PHP 6)</simpara>
</listitem>
<listitem>
<simpara>(array) - cast to array</simpara>
<simpara>(array) - cast to <type>array</type></simpara>
</listitem>
<listitem>
<simpara>(object) - cast to object</simpara>
<simpara>(object) - cast to <type>object</type></simpara>
</listitem>
</itemizedlist>
@ -166,7 +169,8 @@ $foo = ( int ) $bar;
</programlisting>
<para>
Casting a literal strings and variables to binary strings:
Casting literal <type>string</type>s and variables to binary
<type>string</type>s:
</para>
<programlisting role="php">
@ -181,8 +185,8 @@ $binary = b"binary string";
<note>
<para>
Instead of casting a variable to string, you can also enclose the variable
in double quotes.
Instead of casting a variable to a <type>string</type>, it is also possible
to enclose the variable in double quotes.
</para>
<informalexample>
@ -205,7 +209,7 @@ if ($fst === $str) {
<para>
It may not be obvious exactly what will happen when casting between certain
types. For more info, see these sections:
types. For more information, see these sections:
</para>
<itemizedlist>
@ -245,13 +249,6 @@ if ($fst === $str) {
resource</link>
</simpara>
</listitem>
<!-- don't exist yet
<listitem>
<simpara>
<link linkend="language.types.null.casting">Converting to &null;</link>
</simpara>
</listitem>
-->
<listitem>
<simpara>
<link linkend="types.comparisons">The type comparison tables</link>