goba Mon Nov 4 10:45:11 2002 EDT
Modified files:
/phpdoc/en/language types.xml
Log:
Started to clean up the structure, adding some content
in place of TODO comments, and more examples. Also cleaned
up a bit in the formatting.
Index: phpdoc/en/language/types.xml
diff -u phpdoc/en/language/types.xml:1.93 phpdoc/en/language/types.xml:1.94
--- phpdoc/en/language/types.xml:1.93 Mon Nov 4 06:03:25 2002
+++ phpdoc/en/language/types.xml Mon Nov 4 10:45:11 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.93 $ -->
+<!-- $Revision: 1.94 $ -->
<chapter id="language.types">
<title>Types</title>
@@ -7,12 +7,11 @@
<title>Introduction</title>
<simpara>
- PHP supports eight primitive <!-- (all types are primitive in php) -->
- types.
+ PHP supports eight primitive types.
</simpara>
<para>
- Four scalar <!-- (basic, can't be split into parts) --> types:
+ Four scalar types:
<itemizedlist>
@@ -103,10 +102,11 @@
</listitem>
</itemizedlist>
-
+ You may also find some references to the type "double". Consider
+ double the same as float, the two names exist only for historic
+ reasons.
</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
@@ -118,13 +118,36 @@
linkend="language.expressions">expression</link>, use
<function>var_dump</function>.
</simpara>
- <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
- <literal>is_<replaceable>type</replaceable></literal> functions.
- </simpara>
- <!-- TODO: example(s) would be great -->
+ <literal>is_<replaceable>type</replaceable></literal> functions. Some
+ examples:
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+$bool = TRUE; // a boolean
+$str = "foo"; // a string
+$int = 12; // an integer
+
+echo gettype($bool); // prints out "boolean"
+echo gettype($str); // prints out "string"
+
+// If this is an integer, increment it by four
+if (is_int($int)) {
+ $int += 4;
+}
+
+// If $bool is a string, print it out
+// (does not print out anything)
+if (is_string($bool)) {
+ echo "String: $bool";
+}
+]]>
+ </programlisting>
+ </informalexample>
+ </para>
</note>
<simpara>
If you would like to force a variable to be converted to a certain
@@ -133,22 +156,19 @@
use the <function>settype</function> function on it.
</simpara>
<simpara>
- Note that a variable may behave in different manners in certain
+ 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>.
</simpara>
-
-
- </sect1>
+ </sect1>
<sect1 id="language.types.boolean">
<title>Booleans</title>
<simpara>
This is the easiest type. A <type>boolean</type> expresses a
- truth value. It can be either &true; or
- &false;.
+ truth value. It can be either &true; or &false;.
</simpara>
<note>
@@ -162,11 +182,10 @@
<para>
To specify a boolean literal, use either the keyword &true;
or &false;. Both are case-insensitive.
- <!-- technically they are just constants -->
<informalexample>
<programlisting role="php">
<![CDATA[
-$foo = True; // assign the value TRUE to $foo
+$foo = True; // assign the value TRUE to $foo
]]>
</programlisting>
</informalexample>
@@ -180,17 +199,18 @@
<informalexample>
<programlisting role="php">
<![CDATA[
-// == is an operator which returns a boolean
+// == is an operator which test
+// equality and returns a boolean
if ($action == "show_version") {
echo "The version is 1.23";
}
-// this is not necessary:
+// this is not necessary...
if ($show_separators == TRUE) {
echo "<hr>\n";
}
-// because you can simply type this:
+// ...because you can simply type
if ($show_separators) {
echo "<hr>\n";
}
@@ -220,7 +240,7 @@
<itemizedlist>
<listitem>
<simpara>the <link linkend="language.types.boolean">boolean</link>
- &false;<!-- duh... --></simpara>
+ &false; itself</simpara>
</listitem>
<listitem>
<simpara>the <link linkend="language.types.integer">integer</link
@@ -260,12 +280,21 @@
or positive) number!
</simpara>
</warning>
- <!-- TODO: add a few examples, for the people only looking at
- the examples... -->
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+echo gettype((bool) ""); // bool(false)
+echo gettype((bool) 1); // bool(true)
+echo gettype((bool) -2); // bool(true)
+echo gettype((bool) "foo"); // bool(true)
+echo gettype((bool) 2.3e5); // bool(true)
+echo gettype((bool) array(12)); // bool(true)
+echo gettype((bool) array()); // bool(false)
+]]>
+ </programlisting>
+ </informalexample>
</para>
-
- </sect2>
-
+ </sect2>
</sect1>
<sect1 id="language.types.integer">
@@ -303,20 +332,23 @@
]]>
</programlisting>
</example>
- <!--
+ Formally the possible structure for integer literals is:
+ <informalexample>
+ <programlisting>
+<![CDATA[
+decimal : [1-9][0-9]*
+ | 0
- decimal : [1-9][0-9]*
- | 0
-
- hexadecimal : 0[xX][0-9a-fA-F]+
-
- octal : 0[0-7]+
-
- integer : [+-]?decimal
- | [+-]?hexadecimal
- | [+-]?octal
-
- -->
+hexadecimal : 0[xX][0-9a-fA-F]+
+
+octal : 0[0-7]+
+
+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
@@ -372,13 +404,15 @@
<para>
There is no integer division operator in PHP.
<literal>1/2</literal> yields the <type>float</type>
- <literal>0.5</literal>. <!-- See ??? for more information. (with the
- operators, or with type-jug) -->
+ <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[
-var_dump( 25/7 );
-// output: float(3.5714285714286)
+var_dump(25/7); // float(3.5714285714286)
+var_dump((int) (25/7)); // int(3)
+var_dump(round(25/7)); // float(4)
]]>
</programlisting>
</informalexample>
@@ -420,7 +454,6 @@
<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.
@@ -449,7 +482,7 @@
<title>From strings</title>
<simpara>
See <link linkend="language.types.string.conversion">String
- conversion</link>
+ conversion to numbers</link>
</simpara>
</sect3>
@@ -467,16 +500,7 @@
</simpara>
</caution>
</para>
- <!--
-
- IMO, it would more sense as (int) $arr returned the
- number of elements in $arr. This won't break anything,
- since this behaviour was never defined before, and
- (bool)(int) $arr will still behave the same.
-
- -->
</sect3>
-
</sect2>
</sect1>
@@ -485,20 +509,24 @@
<para>
Floating point numbers (AKA "floats", "doubles" or "real numbers") can be
specified using any of the following syntaxes:
- <synopsis>
+ <informalexample>
+ <programlisting role="php">
$a = 1.234; $a = 1.2e3; $a = 7E-10;
- </synopsis>
- <!--
-
-LNUM [0-9]+
-DNUM ([0-9]*[\.][0-9]+)|([0-9]+[\.][0-9]*)
-EXPONENT_DNUM (({LNUM}|{DNUM})[eE][+-]?{LNUM})
-
- -->
+ </programlisting>
+ </informalexample>
+ Formally:
+ <informalexample>
+ <programlisting role="php">
+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 id="warn.float-precision">
<title>Floating point precision</title>
<para>
@@ -526,14 +554,16 @@
</para>
</warning>
- <!-- TODO: add more info -->
<sect2 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>.
+ 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.
</para>
</sect2>
</sect1>
@@ -544,10 +574,8 @@
A <type>string</type> is series of characters. In PHP,
a character is the same as a byte, that is, there are exactly
256 different characters possible. This also implies that PHP
- has no native support of Unicode.
- <!-- how about unicode? will we support that eventually? Are
- there current any ways to work with unicode?
- -->
+ has no native support of Unicode. See <function>utf8_enncode</function>
+ and <function>utf8_decode</function> for some Unicode support.
</para>
<note>
<simpara>
@@ -589,19 +617,19 @@
enclose it in single quotes (the character <literal>'</literal>).
</para>
<para>
- To specify a literal single
+ To specify a literal single
quote, you will need to escape it with a backslash
(<literal>\</literal>), like in many other languages.
If a backslash needs to occur before a single quote or at
the end of the string, you need to double it.
Note that if you try to escape any
- other character, the backslash too will be printed! So
+ other character, the backslash will also be printed! So
usually there is no need to escape the backslash itself.
<note>
<simpara>
In PHP 3, a warning will
be issued at the <literal>E_NOTICE</literal> level when this
- happens.
+ happens.
</simpara>
</note>
<note>
@@ -614,8 +642,8 @@
<programlisting role="php">
<![CDATA[
echo 'this is a simple string';
-echo 'You can also have embedded newlines in strings,
-like this way.';
+echo 'You can also have embedded newlines in strings
+this way';
echo 'Arnold once said: "I\'ll be back"';
// output: ... "I'll be back"
echo 'Are you sure you want to delete C:\\*.*?';
@@ -692,7 +720,7 @@
backslash will be printed too!
</para>
<para>
- But the most important pre of double-quoted strings
+ But the most important feature of double-quoted strings
is the fact that variable names will be expanded.
See <link linkend="language.types.string.parsing">string
parsing</link> for details.
@@ -706,10 +734,10 @@
("<<<"). One should provide an identifier after
<literal><<<</literal>, then the string, and then the
same identifier to close the quotation.
- </simpara>
+ </simpara>
<simpara>
The closing identifier <emphasis>must</emphasis> begin in the
- first column of the line. Also, the identifier used must follow
+ first column of the line. Also, the identifier used must follow
the same naming rules as any other label in PHP: it must contain
only alphanumeric characters and underscores, and must start with
a non-digit character or underscore.
@@ -776,14 +804,13 @@
Heredoc support was added in PHP 4.
</para>
</note>
-
</sect3>
+
<sect3 id="language.types.string.parsing">
<title>Variable parsing</title>
<simpara>
When a string is specified in double quotes or with
- heredoc, variables are
- parsed within it.
+ heredoc, variables are parsed within it.
</simpara>
<simpara>
There are two types of syntax, a
@@ -795,11 +822,10 @@
to parse a variable, an array value, or an object property.
</simpara>
<simpara>
- The complex syntax was introduced in PHP 4,
- <!-- XXX was it? and starting with what version exactly? -->
- and can be recognised
+ The complex syntax was introduced in PHP 4, and can be recognised
by the curly braces surrounding the expression.
</simpara>
+
<sect4 id="language.types.string.parsing.simple">
<title>Simple syntax</title>
<simpara>
@@ -813,7 +839,7 @@
<![CDATA[
$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 "He drank some $beers"; // won't work, 's' is a valid character for varnames
echo "He drank some ${beer}s"; // works
]]>
</programlisting>
@@ -827,19 +853,17 @@
the one with variables.
<!-- XXX isn't &true; :(, this would be the trick
- Also,
- the same trick with curly-braces works if you
- want to limit the greediness of parsers (aren't they
- paying them enough or something?).
+ Also, the same trick with curly-braces works if you
+ want to limit the greediness of parsers.
-->
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
-$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' );
+$fruits = array('strawberry' => 'red', 'banana' => 'yellow');
-// note that this works differently outside string-quotes.
+// note that this works differently outside string-quotes
echo "A banana is $fruits[banana].";
echo "This square is $square->width meters broad.";
@@ -860,6 +884,7 @@
For anything more complex, you should use the complex syntax.
</simpara>
</sect4>
+
<sect4 id="language.types.string.parsing.complex">
<title>Complex (curly) syntax</title>
<simpara>
@@ -912,8 +937,9 @@
</para>
<note>
<simpara>
- For backwards compatibility, you can still use the array-braces.
- However, this syntax is deprecated as of PHP 4.
+ For backwards compatibility, you can still use array-braces
+ for the same purpose. However, this syntax is deprecated as
+ of PHP 4.
</simpara>
</note>
<para>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
