jeroen Wed May 16 08:22:22 2001 EDT
Modified files:
/phpdoc/en/language types.xml
Log:
- Begin with revision of language section.
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 >
Index: phpdoc/en/language/types.xml
diff -u phpdoc/en/language/types.xml:1.20 phpdoc/en/language/types.xml:1.21
--- phpdoc/en/language/types.xml:1.20 Thu May 10 23:34:13 2001
+++ phpdoc/en/language/types.xml Wed May 16 08:22:22 2001
@@ -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>
+ <link linkend="language.types.boolean">boolean</link>
</simpara>
</listitem>
+
<listitem>
<simpara>
- <link linkend="language.types.boolean">booleans</link>
+ <link linkend="language.types.integer">integer</link>
</simpara>
</listitem>
+
<listitem>
<simpara>
- <link linkend="language.types.double">floating-point numbers
- </link>
+ <link linkend="language.types.double">floating-point number (double)</link>
</simpara>
</listitem>
+
<listitem>
<simpara>
- <link linkend="language.types.integer">integer</link>
+ <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.string">string</link>
+ <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 @@
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 @@
var $bar;
function foo() {
- $this->foo = 'Foo';
- $this->bar = array('Bar1', 'Bar2', 'Bar3');
+ $this->foo = 'Foo';
+ $this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
@@ -248,7 +465,7 @@
echo <<<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->bar[1]}.
This should print a capital 'A': \x41
EOT;
?>
@@ -307,7 +524,7 @@
</para>
<sect2 id="language.types.string.parsing">
<title>String parsing</title>
- <!-- Section orig. by [EMAIL PROTECTED],
+ <!--
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 @@
</simpara>
<informalexample>
<programlisting role="php">
- $fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' );
+ $fruits = array( 'strawberry' => 'red' , 'banana' => '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->width meters broad.";
+ echo "This square is $square->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 @@
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 @@
$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->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->values[3]->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 @@
</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 @@
<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 @@
</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 @@
</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
