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

step two: massive whitespace updates. types.xml (containing the entire description of PHP types) was a very large file, and has now been split in several files in en/language/types. No content has been changed whatsoever at this point. This commit fixes whitespace across the board in all the files, and contains no other changes.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@252928 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind 2008-02-14 20:50:33 +00:00
parent 5b09b299d6
commit 123738b556
11 changed files with 1721 additions and 1664 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
language/types.xml
View file

@ -1,9 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.196 $ -->
<chapter xml:id="language.types" xmlns="http://docbook.org/ns/docbook">
<title>Types</title>
<!-- $Revision: 1.197 $ -->
<chapter xml:id="language.types" xmlns="http://docbook.org/ns/docbook">
<title>Types</title>
<sect1 xml:id="language.types.intro">
<sect1 xml:id="language.types.intro">
<title>Introduction</title>
<simpara>
@ -104,6 +104,7 @@
</itemizedlist>
And the pseudo-variable <parameter>$...</parameter>.
</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
@ -115,12 +116,14 @@
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>
<para>
If you simply want a human-readable representation of the type for
debugging, use <function>gettype</function>. To check for a certain type,
@ -155,12 +158,14 @@ if (is_string($a_bool)) {
</informalexample>
</para>
</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 be evaluated with different values in certain
situations, depending on what type it is at the time. For more
@ -183,7 +188,7 @@ if (is_string($a_bool)) {
&language.types.psuedo-types;
&language.types.type-juggling;
</chapter>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:

824
language/types/array.xml
View file

File diff suppressed because it is too large Load diff

214
language/types/boolean.xml
View file

@ -1,42 +1,41 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml: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>
<!-- $Revision: 1.2 $ -->
<sect1 xml: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>
<note>
<simpara>
The boolean 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.
<informalexample>
<programlisting role="php">
<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.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$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="language.control-structures">control
structure</link>.
<informalexample>
<programlisting role="php">
</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="language.control-structures">control structure</link>.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// == is an operator which test
@ -56,78 +55,85 @@ if ($show_separators) {
}
?>
]]>
</programlisting>
</informalexample>
</para>
</sect2>
</programlisting>
</informalexample>
</para>
</sect2>
<sect2 xml:id="language.types.boolean.casting">
<title>Converting to boolean</title>
<sect2 xml: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>
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.
the <link linkend="language.types.boolean">boolean</link> &false; itself
</simpara>
</listitem>
<listitem>
<simpara>
See also <link linkend="language.types.type-juggling">Type Juggling</link>.
the <link linkend="language.types.integer">integer</link> 0 (zero)
</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; itself</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 member variables (PHP 4 only)</simpara>
</listitem>
<listitem>
<simpara>the special type <link linkend="language.types.null"
>NULL</link> (including unset variables)
</simpara>
</listitem>
<listitem>
<simpara><link linkend="ref.simplexml">SimpleXML</link>
objects created from empty tags
</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>
<informalexample>
<programlisting role="php">
</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 member
variables (PHP 4 only)
</simpara>
</listitem>
<listitem>
<simpara>
the special type <link linkend="language.types.null">NULL</link>
(including unset variables)
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="ref.simplexml">SimpleXML</link> objects created from empty
tags
</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>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
var_dump((bool) ""); // bool(false)
@ -140,12 +146,12 @@ var_dump((bool) array()); // bool(false)
var_dump((bool) "false"); // bool(true)
?>
]]>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

126
language/types/float.xml
View file

@ -1,12 +1,14 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<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:
<informalexample>
<programlisting role="php">
<!-- $Revision: 1.2 $ -->
<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:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$a = 1.234;
@ -14,64 +16,68 @@ $b = 1.2e3;
$c = 7E-10;
?>
]]>
</programlisting>
</informalexample>
Formally:
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
Formally:
<informalexample>
<programlisting role="php">
<![CDATA[
LNUM [0-9]+
DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
]]>
</programlisting>
</informalexample>
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 xml: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>
</programlisting>
</informalexample>
<sect2 xml:id="language.types.float.casting">
<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.
</para>
</sect2>
</sect1>
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 xml: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>
<sect2 xml:id="language.types.float.casting">
<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.
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

358
language/types/integer.xml
View file

@ -1,33 +1,36 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml: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 length integer / GMP</link>,
<link linkend="language.types.float">Floating point numbers</link>, and
<link linkend="ref.bc">Arbitrary precision / BCMath</link>
</para>
<!-- $Revision: 1.2 $ -->
<sect1 xml: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 length integer / GMP</link>,
<link linkend="language.types.float">Floating point numbers</link>, and
<link linkend="ref.bc">Arbitrary precision / BCMath</link>
</para>
<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 +).
</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">
<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 +).
</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[
<?php
$a = 1234; // decimal number
@ -36,11 +39,13 @@ $a = 0123; // octal number (equivalent to 83 decimal)
$a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
?>
]]>
</programlisting>
</example>
Formally the possible structure for integer literals is:
<informalexample>
<programlisting>
</programlisting>
</example>
Formally the possible structure for integer literals is:
<informalexample>
<programlisting>
<![CDATA[
decimal : [1-9][0-9]*
| 0
@ -53,45 +58,46 @@ integer : [+-]?decimal
| [+-]?hexadecimal
| [+-]?octal
]]>
</programlisting>
</informalexample>
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.
</para>
<warning>
<para>
If an invalid digit is passed to octal integer (i.e. 8 or 9), the rest
of the number is ignored.
<example>
<title>Octal weirdness</title>
<programlisting role="php">
</programlisting>
</informalexample>
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.
</para>
<warning>
<para>
If an invalid digit is passed to octal integer (i.e. 8 or 9), the rest of
the number is ignored.
<example>
<title>Octal weirdness</title>
<programlisting role="php">
<![CDATA[
<?php
var_dump(01090); // 010 octal = 8 decimal
?>
]]>
</programlisting>
</example>
</para>
</warning>
</sect2>
<sect2 xml: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.
</programlisting>
</example>
</para>
</warning>
</sect2>
<informalexample>
<programlisting role="php">
<sect2 xml: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[
<?php
$large_number = 2147483647;
@ -116,30 +122,32 @@ 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>. You can cast the value to
an integer to always round it downwards, or you can
use the <function>round</function> function.
<informalexample>
<programlisting role="php">
</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>. You can cast the value to an
integer to always round it downwards, or you can use the
<function>round</function> function.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
var_dump(25/7); // float(3.5714285714286)
@ -147,97 +155,101 @@ var_dump((int) (25/7)); // int(3)
var_dump(round(25/7)); // float(4)
?>
]]>
</programlisting>
</informalexample>
</para>
</sect2>
</programlisting>
</informalexample>
</para>
</sect2>
<sect2 xml: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 an <type>integer</type> argument. You can also convert a value to
integer with the function <function>intval</function>.
</simpara>
<simpara>
See also <link linkend="language.types.type-juggling">type-juggling</link>.
</simpara>
<sect3 xml:id="language.types.integer.casting.from-boolean">
<title>From <link linkend="language.types.boolean">booleans</link></title>
<sect2 xml: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 an <type>integer</type> argument.
You can also convert a value to integer with the function
<function>intval</function>.
</simpara>
<simpara>
See also <link linkend="language.types.type-juggling">type-juggling</link>.
</simpara>
<sect3 xml: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>
<simpara>
&false; will yield <literal>0</literal> (zero), and &true; will yield
<literal>1</literal> (one).
</simpara>
</sect3>
<sect3 xml: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 <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">
<sect3 xml: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
<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[
<?php
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 xml:id="language.types.integer.casting.from-string">
<title>From strings</title>
<simpara>
See <link linkend="language.types.string.conversion">String
conversion to numbers</link>
</simpara>
</sect3>
<sect3 xml: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> rely on this behaviour, as it can
change without notice.
</simpara>
</caution>
</para>
</sect3>
</sect2>
</sect1>
</programlisting>
</informalexample>
See for more information the <link linkend="warn.float-precision">warning
about float-precision</link>.
</para>
</warning>
</sect3>
<sect3 xml:id="language.types.integer.casting.from-string">
<title>From strings</title>
<simpara>
See <link linkend="language.types.string.conversion">String conversion to
numbers</link>
</simpara>
</sect3>
<sect3 xml: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> rely on this
behaviour, as it can change without notice.
</simpara>
</caution>
</para>
</sect3>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

100
language/types/null.xml
View file

@ -1,59 +1,65 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<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>.
</para>
<note>
<simpara>
The null type was introduced in PHP 4.
</simpara>
</note>
<!-- $Revision: 1.2 $ -->
<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>.
</para>
<note>
<simpara>
The null type was introduced in PHP 4.
</simpara>
</note>
<para>
A variable is considered to be &null; if
<itemizedlist>
<listitem>
<para>
A variable is considered to be &null; if
<itemizedlist>
<listitem>
<para>
it has been assigned the constant &null;.
</para>
</listitem>
<listitem>
<para>
it has not been set to any value yet.
</para>
</listitem>
<listitem>
<para>
it has been <function>unset</function>.
</para>
</listitem>
</itemizedlist>
it has been assigned the constant &null;.
</para>
<sect2 xml:id="language.types.null.syntax">
<title>Syntax</title>
</listitem>
<listitem>
<para>
There is only one value of type &null;, and that is
the case-insensitive keyword &null;.
<informalexample>
<programlisting role="php">
it has not been set to any value yet.
</para>
</listitem>
<listitem>
<para>
it has been <function>unset</function>.
</para>
</listitem>
</itemizedlist>
</para>
<sect2 xml: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">
<![CDATA[
<?php
$var = NULL;
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
See also <function>is_null</function> and <function>unset</function>.
</para>
</sect2>
</sect1>
</programlisting>
</informalexample>
</para>
<para>
See also <function>is_null</function> and <function>unset</function>.
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

78
language/types/object.xml
View file

@ -1,17 +1,17 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="language.types.object">
<title>Objects</title>
<!-- $Revision: 1.2 $ -->
<sect1 xml:id="language.types.object">
<title>Objects</title>
<sect2 xml:id="language.types.object.init">
<title>Object Initialization</title>
<sect2 xml: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.
<para>
To initialize an object, you use the <literal>new</literal> statement to
instantiate the object to a variable.
<informalexample>
<programlisting role="php">
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
class foo
@ -26,40 +26,42 @@ $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>
<sect2 xml:id="language.types.object.casting">
<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.
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<simpara>
For a full discussion, please read the section
<link linkend="language.oop">Classes and Objects</link>.
</simpara>
</sect2>
<sect2 xml:id="language.types.object.casting">
<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.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$obj = (object) 'ciao';
echo $obj->scalar; // outputs 'ciao'
?>
]]>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

195
language/types/psuedo-types.xml
View file

@ -1,73 +1,73 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="language.pseudo-types">
<title>Pseudo-types and variables used in this documentation</title>
<!-- $Revision: 1.2 $ -->
<sect1 xml:id="language.pseudo-types">
<title>Pseudo-types and variables used in this documentation</title>
<sect2 xml:id="language.types.mixed">
<title>mixed</title>
<para>
<literal>mixed</literal> indicates that a parameter may accept multiple (but not
necessarily all) types.
</para>
<para>
<function>gettype</function> for example will accept all PHP types,
while <function>str_replace</function> will accept strings and arrays.
</para>
</sect2>
<sect2 xml:id="language.types.number">
<title>number</title>
<para>
<literal>number</literal> indicates that a parameter can be either
<type>integer</type> or <type>float</type>.
</para>
</sect2>
<sect2 xml:id="language.types.mixed">
<title>mixed</title>
<sect2 xml:id="language.types.callback">
<title>callback</title>
<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.
</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
<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.
</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.
</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.
</para>
<para>
Apart from common user-defined function,
<function>create_function</function> can be used to create an anonymous
callback function.
</para>
<para>
<literal>mixed</literal> indicates that a parameter may accept multiple (but
not necessarily all) types.
</para>
<para>
<example>
<title>
Callback function examples
</title>
<programlisting role="php">
<para>
<function>gettype</function> for example will accept all PHP types, while
<function>str_replace</function> will accept strings and arrays.
</para>
</sect2>
<sect2 xml:id="language.types.number">
<title>number</title>
<para>
<literal>number</literal> indicates that a parameter can be either
<type>integer</type> or <type>float</type>.
</para>
</sect2>
<sect2 xml:id="language.types.callback">
<title>callback</title>
<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.
</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
<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.
</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.
</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.
</para>
<para>
Apart from common user-defined function, <function>create_function</function>
can be used to create an anonymous callback function.
</para>
<para>
<example>
<title>
Callback function examples
</title>
<programlisting role="php">
<![CDATA[
<?php
@ -112,38 +112,41 @@ class B extends A {
call_user_func(array('B', 'parent::who')); // A
?>
]]>
</programlisting>
</example>
</para>
<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 <link linkend="language.references">References Explained</link>.
</simpara>
</note>
</programlisting>
</example>
</para>
</sect2>
<sect2 xml:id="language.types.void">
<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 doesn't accept any parameters.
</para>
</sect2>
<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
<link linkend="language.references">References Explained</link>.
</simpara>
</note>
<sect2 xml:id="language.types.dotdotdot">
<title>...</title>
<para>
<parameter>$...</parameter> in function prototypes means
<literal>and so on</literal>.
This variable name is used when a function can take an endless number of
arguments.
</para>
</sect2>
</sect1>
</sect2>
<sect2 xml:id="language.types.void">
<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
doesn't accept any parameters.
</para>
</sect2>
<sect2 xml:id="language.types.dotdotdot">
<title>...</title>
<para>
<parameter>$...</parameter> in function prototypes means
<literal>and so on</literal>. This variable name is used when a function can
take an endless number of arguments.
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

106
language/types/resource.xml
View file

@ -1,63 +1,57 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml: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>
<!-- $Revision: 1.2 $ -->
<sect1 xml: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>
<para>
See also <function>get_resource_type</function>.
</para>
<para>
See also <function>get_resource_type</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.
</para>
</sect2>
<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.
</para>
</sect2>
<sect2 xml:id="language.types.resource.self-destruct">
<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.
<note>
<simpara>
Persistent database links are special, they
are <emphasis>not</emphasis> destroyed by the
garbage collector. See also the section about <link
linkend="features.persistent-connections">persistent
connections</link>.
</simpara>
</note>
</para>
</sect2>
</sect1>
<sect2 xml:id="language.types.resource.self-destruct">
<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.
<note>
<simpara>
Persistent database links are special, they are <emphasis>not</emphasis>
destroyed by the garbage collector. See also the section about
<link linkend="features.persistent-connections">persistent
connections</link>.
</simpara>
</note>
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:

1013
language/types/string.xml
View file

File diff suppressed because it is too large Load diff

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

@ -1,27 +1,27 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="language.types.type-juggling">
<title>Type Juggling</title>
<!-- $Revision: 1.2 $ -->
<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.
</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">
<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">
<![CDATA[
<?php
$foo = "0"; // $foo is string (ASCII 48)
@ -50,35 +50,38 @@ examples:
- -'abc' = 'abc'
-->
</programlisting>
</informalexample>
</para>
<simpara>
If the last two examples above seem odd, see <link
linkend="language.types.string.conversion">String
conversion to numbers</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.
</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:
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<simpara>
If the last two examples above seem odd, see
<link linkend="language.types.string.conversion">String conversion to
numbers</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.
</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:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$a = 'car'; // $a is a string
@ -86,93 +89,103 @@ $a[0] = 'b'; // $a is still a string
echo $a; // bar
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
See the section titled <link linkend="language.types.string.substr">String
access by character</link> for more information.
</para>
</note>
</programlisting>
</informalexample>
</para>
<sect2 xml:id="language.types.typecasting">
<title>Type Casting</title>
<para>
See the section titled <link linkend="language.types.string.substr">String
access by character</link> for more information.
</para>
</note>
<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">
<sect2 xml: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">
<![CDATA[
<?php
$foo = 10; // $foo is an integer
$bar = (boolean) $foo; // $bar is a boolean
?>
]]>
</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>(binary) - cast to binary string (PHP 6)</simpara>
</listitem>
<listitem>
<simpara>(array) - cast to array</simpara>
</listitem>
<listitem>
<simpara>(object) - cast to object</simpara>
</listitem>
</itemizedlist>
</para>
<para>
(binary) casting and b prefix forward support was added in PHP 5.2.1
</para>
<para>
Note that tabs and spaces are allowed inside the parentheses, so
the following are functionally equivalent:
<informalexample>
<programlisting role="php">
</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>(binary) - cast to binary string (PHP 6)</simpara>
</listitem>
<listitem>
<simpara>(array) - cast to array</simpara>
</listitem>
<listitem>
<simpara>(object) - cast to object</simpara>
</listitem>
</itemizedlist>
</para>
<para>
(binary) casting and b prefix forward support was added in PHP 5.2.1
</para>
<para>
Note that tabs and spaces are allowed inside the parentheses, so the
following are functionally equivalent:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>
]]>
</programlisting>
<para>
Casting a literal strings and variables to binary strings:
</para>
<programlisting role="php">
</programlisting>
<para>
Casting a literal strings and variables to binary strings:
</para>
<programlisting role="php">
<![CDATA[
<?php
$binary = (binary)$string;
$binary = b"binary string";
?>
]]>
</programlisting>
</informalexample>
</para>
<note>
<para>
Instead of casting a variable to string, you can also enclose
the variable in double quotes.
<informalexample>
<programlisting role="php">
</programlisting>
</informalexample>
</para>
<note>
<para>
Instead of casting a variable to string, you can also enclose
the variable in double quotes.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$foo = 10; // $foo is an integer
@ -185,59 +198,60 @@ if ($fst === $str) {
}
?>
]]>
</programlisting>
</informalexample>
</para>
</note>
<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>
<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>
<!-- 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>
</simpara>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</programlisting>
</informalexample>
</para>
</note>
<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>
<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>
<!-- 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>
</simpara>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables: