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

- Begin with revision of language section.

Browse source 
basic-syntax:
  - Added note about revision, and progress-info
  - Explained escaping a bit more eleborately
  - Explained escaping inside control structures
     (quite badly, I admit, but still)

  types:
  - Added null and resource
  - Categorized in scalars, compound and special
  - Added 'converting to xxx' section for
    boolean and integer (rest follows some day)
  - Moved 'when is something considered true'
    to that new section, and updated it.
  - Added overflow and converting notes to
    integer. Referred to float-precision warning.
  - Added section about resource-freeing
  - In type-juggling, referred to the new 'convert
    to xxx' sections.

- fixed some xml-tags
- converted most > to >


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@47585 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeroen van Wolffelaar 2001-05-16 15:22:22 +00:00
parent 64e21277b7
commit c72fc51e9a
1 changed files with 358 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

427
language/types.xml
View file

@ -1,42 +1,88 @@
<chapter id="language.types">
<title>Types</title>
<sect1 id="language.types.intro">
<title>Introduction</title>
<simpara>
PHP supports eight primitive <!-- (all types are primitive in php) -->
types.
</simpara>
<para>
PHP supports the following types:
Three scalar <!-- (basic, can't be split into parts) --> types:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.array">array</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.boolean">booleans</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.double">floating-point numbers
</link>
<link linkend="language.types.boolean">boolean</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.integer">integer</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.object">object</link>
<link linkend="language.types.double">floating-point number (double)</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.string">string</link>
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Three compound types:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.array">array</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.object">object</link>
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
And finally two special types:
<itemizedlist>
<listitem>
<simpara>
<link linkend="language.types.resource">resource</link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="language.types.null">null</link>
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
The type of a variable is usually not set by the programmer;
rather, it is decided at runtime by PHP depending on the context in
@ -55,11 +101,95 @@
linkend="language.types.type-juggling">Type Juggling</link>.
</simpara>
</sect1>
<sect1 id="language.types.boolean">
<title>Booleans</title>
<para>
This is the simpelest. Either TRUE or FALSE. <!-- more to come -->
</para>
<simpara>
This is the simpelest type. A <type>boolean</type> expresses a
truth value. It can be either TRUE or FALSE.
</simpara>
<simpara>
You can use the special case-insensitive constants 'TRUE' and
'FALSE' to specify a <type>boolean</type> value. Usually you
use some kind of <link linkend="language.operators">operator</link>
which returns a <type>boolean</type> value, and then pass it
on to a <link linkend="control-structures">control
structure</link>.
</simpara>
<!-- TODO: example of this -->
<!-- TODO: example to show that if ( expr == TRUE ) is not really
necessary... (i've seen this construct numerous times)
-->
<!-- TODO: how others vars are converted to boolean -->
<note>
<simpara>
The boolean-type was introduced in PHP 4
</simpara>
</note>
<sect2 id="language.types.boolean.casting">
<title>Converting to boolean</title>
<simpara>
See <link linkend="language.types.type-juggling">type-juggling</link>
for general information about converting.
</simpara>
<para>
When converting to <type>boolean</type>, the following values
are considered FALSE:
<itemizedlist>
<listitem>
<simpara>the <link linkend="language.types.boolean">boolean</link>
FALSE<!-- duh... --></simpara>
</listitem>
<listitem>
<simpara>the <link linkend="language.types.integer">integer</link
> 0 (zero) </simpara>
</listitem>
<listitem>
<simpara>the <link linkend="language.types.double">float</link>
0.0 (zero) </simpara>
</listitem>
<listitem>
<simpara>the empty <link linkend="language.types.string"
>string</link>, and the <link linkend="language.types.string"
>string</link>
"0"</simpara>
</listitem>
<listitem>
<simpara>an <link linkend="language.types.array">array</link>
with zero elements</simpara>
</listitem>
<listitem>
<simpara>an <link linkend="language.types.object">object</link>
with zero elements</simpara>
</listitem>
<listitem>
<simpara>the special value <link linkend="language.types.null"
>NULL</link>
</simpara>
</listitem>
</itemizedlist>
Every other value is considered TRUE (including any
<link linkend="language.types.resource">resource</link>).
<warning><simpara>-1 is considered TRUE!</simpara></warning>
<!-- and/or a few examples, for the people only looking at
the examples... </XXX> -->
</para>
</sect2>
</sect1>
<sect1 id="language.types.integer">
@ -78,23 +208,110 @@ $a = 0x12; # hexadecimal number (equivalent to 18 decimal)
maximum value of about 2 billion is the usual value
(that's 32 bits signed).
</para>
<sect2 id="language.types.integer.overflow">
<title>Integer overflow</title>
<para>
Because of the flexible type-juggling, a number
is autmatically converted to float when it is about
to overflow.
</para>
</sect2>
<sect2 id="language.types.integer.casting">
<title>Converting to integer</title>
<simpara>
See <link linkend="language.types.type-juggling">type-juggling</link> for
general information about converting.
</simpara>
<sect3 id="language.types.integer.casting.from-boolean">
<title>From <link linkend="language.types.boolean"
>booleans</link></title>
<simpara>
<link linkend="language.types.boolean">False</link> will yield
0 (zero), and <link linkend="language.types.boolean">True</link>
will yield 1 (one).
</simpara>
</sect3>
<sect3 id="language.types.integer.casting.from-float">
<title>From floating point numbers</title>
<simpara>
When converting from float to integer, the number will
be rounded <emphasis>towards zero</emphasis>.
</simpara>
<para>
If the float is beyond the boundaries of integer
<!-- usually, or is it 'always'? -->
(usually <literal>+/- 2.15e+9 = 2^31</literal>),
the result is undefined, since the float hasn't
got enough precision to give an exact integer result.
<warning>
<simpara>
No warning, not even a notice will be issued in this
case!
</simpara>
</warning>
</para>
<warning><para>
Never cast an unknown fraction to <type>integer</type>, as this can
sometimes lead to unexpected results.
<informalexample><programlisting role="php">
echo (int) ( (0.1+0.7) * 10 ); // echo's 7!
</programlisting></informalexample>
See for more information the <link
linkend="warn.float-precision">warning
about float-precision</link>.
</para></warning>
</sect3>
<sect3 id="language.types.integer.casting.from-string">
<title>From strings</title>
<simpara>
See <link linkend="language.types.string.conversion">String
conversion</link>
</simpara>
</sect3>
</sect2>
<para>
See also:
<link linkend="ref.gmp">Arbitrary precision integeres</link> and
<link linkend="language.types.double">Floating point numbers</link>
</para>
</sect1>
<sect1 id="language.types.double">
<title>Floating point numbers</title>
<para>
Floating point numbers ("doubles") can be specified using any of
the following syntaxes:
Floating point numbers (aka "doubles" or "real numbers") can be
specified using any of the following syntaxes:
<informalexample>
<programlisting role="php">
$a = 1.234; $a = 1.2e3;
$a = 1.234; $a = 1.2e3; $a = 7E-10;
</programlisting>
</informalexample>
<!--
LNUM [0-9]+
DNUM ([0-9]*[\.][0-9]+)|([0-9]+[\.][0-9]*)
EXPONENT_DNUM (({LNUM}|{DNUM})[eE][+-]?{LNUM})
-->
The size of a floating point number is platform-dependent,
although a maximum of ~1.8e308 with a precision of roughly 14
decimal digits is a common value (that's 64 bit IEEE format).
</para>
<warning id="warn.float-precision">
<title>Floating point precision</title>
<para>
It is quite usual that simple decimal fractions like
<literal>0.1</literal> or <literal>0.7</literal> cannot be
@ -238,8 +455,8 @@ class foo {
var $bar;
function foo() {
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
$this-&gt;foo = 'Foo';
$this-&gt;bar = array('Bar1', 'Bar2', 'Bar3');
}
}
@ -248,7 +465,7 @@ $name = 'MyName';
echo &lt;&lt;&lt;EOT
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
Now, I am printing some {$foo-&gt;bar[1]}.
This should print a capital 'A': \x41
EOT;
?>
@ -307,7 +524,7 @@ $last = $str[strlen($str)-1];
</para>
<sect2 id="language.types.string.parsing">
<title>String parsing</title>
<!-- Section orig. by jeroen@a-es2.uu.nl,
<!--
I used simpara all over, because I don't know when
to use para. There will also probably some typo's
and misspellings.
@ -366,10 +583,10 @@ $last = $str[strlen($str)-1];
</simpara>
<informalexample>
<programlisting role="php">
$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' );
$fruits = array( 'strawberry' =&gt; 'red' , 'banana' =&gt; 'yellow' );
echo "A banana is $fruits[banana].";
echo "This square is $square->width meters broad.";
echo "This square is $square->width00 centimeters broad."; // won't work,
echo "This square is $square-&gt;width meters broad.";
echo "This square is $square-&gt;width00 centimeters broad."; // won't work,
// for a solution, see the <link linkend="language.types.string.parsing.complex">complex syntax</link>.
<!-- XXX this won't work:
@ -397,7 +614,7 @@ $last = $str[strlen($str)-1];
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 "{$").
(Use "{\$" or "\{$" to get a literal "{$").
Some examples to make it clear:
</simpara>
<informalexample>
@ -405,13 +622,13 @@ $last = $str[strlen($str)-1];
$great = 'fantastic';
echo "This is { $great}"; // won't work, outputs: This is { fantastic}
echo "This is {$great}"; // works, outputs: This is fantastic
echo "This square is {$square->width}00 centimeters broad.";
echo "This square is {$square-&gt;width}00 centimeters broad.";
echo "This works: {$arr[4][3]}";
echo "This is wrong: {$arr[foo][3]}"; // for the same reason
// as $foo[bar] is wrong outside a string.
<!-- XXX see the still-to-write explaination in the arrays-section. -->
echo "You should do it this way: {$arr['foo'][3]}";
echo "You can even write {$obj->values[3]->name}";
echo "You can even write {$obj-&gt;values[3]-&gt;name}";
echo "This is the value of the var named $name: {${$name}}";
<!-- <xxx> maybe it's better to leave this out?? -->
@ -452,14 +669,14 @@ $last = $str[strlen($str)-1];
</simpara>
<informalexample>
<programlisting role="php">
$foo = 1 + "10.5"; // $foo is double (11.5)
$foo = 1 + "-1.3e3"; // $foo is double (-1299)
$foo = 1 + "10.5"; // $foo is float (11.5)
$foo = 1 + "-1.3e3"; // $foo is float (-1299)
$foo = 1 + "bob-1.3e3"; // $foo is integer (1)
$foo = 1 + "bob3"; // $foo is integer (1)
$foo = 1 + "10 Small Pigs"; // $foo is integer (11)
$foo = 1 + "10 Little Piggies"; // $foo is integer (11)
$foo = "10.0 pigs " + 1; // $foo is integer (11)
$foo = "10.0 pigs " + 1.0; // $foo is double (11)
$foo = "10.0 pigs " + 1.0; // $foo is float (11)
</programlisting>
</informalexample>
<simpara>
@ -570,7 +787,7 @@ echo "This won't work: $a[3][bar]";
<informalexample>
<programlisting role="php">
$a[3]['bar'] = 'Bob';
echo "This will work: " . $a[3][bar];
echo "This will work: " . $a[3]['bar'];
</programlisting>
</informalexample>
</para>
@ -678,6 +895,66 @@ $bar->do_foo();
</sect2>
</sect1>
<sect1 id="language.types.resource">
<title>Resource</title>
<para>
A resource is a special variable, holding
a reference to an external resource. Resources
are created and used by special functions.
See the <link linkend="resource">appendix</link>
for a listing of all these
functions and the corresponding resource-types.
</para>
<note>
<simpara>
The resource-type was introduced in PHP 4
</simpara>
</note>
<sect2 id="language.types.resource.self-destruct">
<title>Freeing resources</title>
<para>
Due to the reference-counting system introduced
with PHP4's Zend-engine, it is automatically detected
when a resource is no longer referred to (just
like Java). When this is
the case, all resources that were in use for this
resource are made free by the garbage collector.
For this reason, it is rarely ever necessary to
free the memory manually by using some free_result
function.
<note>
<simpara>
Persistant database-links are special, they
are <emphasis>not</emphasis> destroyed by the
gc. See also <link
linkend="features.persistent-connections">persistent
links</link>
</simpara>
</note>
</para>
</sect2>
</sect1>
<sect1 id="language.types.null">
<title>Null</title>
<note>
<simpara>
The null-type was introduced in PHP 4
</simpara>
</note>
</sect1>
<sect1 id="language.types.type-juggling">
<title>Type Juggling</title>
@ -814,46 +1091,58 @@ $foo = ( int ) $bar;
</para>
<para>
It may not be obvious exactly what will happen when casting
between certain types. For instance, the following should be
noted.
between certain types. For more info, see these sections:
<itemizedlist>
<listitem>
<simpara><link linkend="language.types.boolean.casting">Converting to
boolean</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.integer.casting">Converting to
integer</link></simpara>
</listitem>
<!-- don't exist yet
<listitem>
<simpara><link linkend="language.types.double.casting">Converting to
float</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.string.casting">Converting to
string</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.array.casting">Converting to
array</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.object.casting">Converting to
object</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.resource.casting">Converting to
resource</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="language.types.null.casting">Converting to
null</link></simpara>
</listitem>
-->
</itemizedlist>
</para>
<para>
When converting to boolean, the following values are considered
FALSE:
<itemizedlist>
<listitem>
<simpara>the boolean FALSE<!-- duh... --></simpara>
</listitem>
<listitem>
<simpara>the integer 0 (zero) </simpara>
</listitem>
<listitem>
<simpara>the float 0.0 (zero) </simpara>
</listitem>
<listitem>
<simpara>the empty string, and the string "0"</simpara>
</listitem>
<listitem>
<simpara>an array with zero elements</simpara>
</listitem>
<listitem>
<simpara>an object with zero elements</simpara>
</listitem>
</itemizedlist>
Every other value is considered true.
<!-- <XXX> this should be such a cute warning thing... -->
(-1 is considered TRUE!).
<!-- and/or a few examples, for the people only looking at
the examples... </XXX> -->
</para>
<para>
<!-- TODO: move to 'converting to string' -->
When casting or forcing a conversion from array to string, the
result will be the word <literal>Array</literal>. When casting or
forcing a conversion from object to string, the result will be
the word <literal>Object</literal>. In both cases a warning will
be issued.
the word <literal>Object</literal>.
<!-- not with my PHP, not even a notice... maybe in PHP3?
Does someone know?
In both cases a warning will
be issued. -->
</para>
<para>
When casting from a scalar or a string variable to an array, the