From 00f873a1d9fc9b118723fd64d57a2d301de2051a Mon Sep 17 00:00:00 2001 From: Jeroen van Wolffelaar Date: Sat, 19 May 2001 20:45:31 +0000 Subject: [PATCH] - added note about 'mixed' type - added boolean syntax, and some examples - changed float to double as much as possible - re-sectionized integer. added note about integer division, notes about integer-overflow (== type juggling in fact) - Noted that behaviour of converting to int is undefined in cases other than boolean and string. - Completely revised arrays (I skipped string for now) BTW: Not totally ready yet, but ready enough to include. It is properly defined, only examples and more explaination etc could be useful. - Removed ++ and -- operator for strings. It is at best very complex how it works, at worst buggy. Though in certain cases it can be useful, it will return with proper definition. - Noted (in comment for now) that copying arrays works strange when there are references to some elements. - minor layout-improvements - typo's git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@47890 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/types.xml | 735 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 649 insertions(+), 86 deletions(-) diff --git a/language/types.xml b/language/types.xml index d911eae899..72947aaeb2 100644 --- a/language/types.xml +++ b/language/types.xml @@ -39,9 +39,7 @@ - - Two compound types: @@ -59,10 +57,7 @@ - - - And finally two special types: @@ -81,6 +76,25 @@ + + + + In this manual you'll often find mixed parameters. + This pseudo-type + indicates multiple possiblities for that parameter. + + + @@ -108,43 +122,74 @@ Booleans - This is the simpelest type. A boolean expresses a - truth value. It can be either TRUE or FALSE. + This is the easiest type. A boolean expresses a + truth value. It can be either true or + false. - - - You can use the special case-insensitive constants 'TRUE' and - 'FALSE' to specify a boolean value. Usually you - use some kind of operator - which returns a boolean value, and then pass it - on to a control - structure. - - - - - - - - The boolean-type was introduced in PHP 4 + The boolean-type was introduced in PHP 4. - + + + Syntax + + To specify a boolean-literal, use either the keyword TRUE + or FALSE. Both are case-insensitive. + + + +$foo = True; // assign the value TRUE to $foo + + + + + Usually you + use some kind of operator + which returns a boolean value, and then pass it + on to a control + structure. + + +if ($action == "show_version") // == is an operator which returns a boolean +{ + echo "The version is 1.23"; +} + +// this is not necessary: +if ($show_separators == true) +{ + echo "<hr>\n"; +} + +// because you can simply type this: +if ($show_separators) +{ + echo "<hr>\n"; +} + + + + + Converting to boolean - See type-juggling - for general information about converting. + To explicitely convert a value to boolean, use either + the (bool) or the (boolean) cast. + However, in most cases you do not need to use the cast, since a value + will be autmatically converted if an operator, function or + control-structure requires a boolean-argument. + + + See also type-juggling. When converting to boolean, the following values - are considered FALSE: + are considered FALSE: @@ -156,7 +201,7 @@ > 0 (zero) - the float + the double 0.0 (zero) @@ -180,41 +225,115 @@ - Every other value is considered TRUE (including any + Every other value is considered TRUE (including any resource). - -1 is considered TRUE! - + + + -1 is considered + TRUE, like any other non-zero (whether negative + or positive) number! + + + - - Integers - - Integers can be specified using any of the following syntaxes: - - + Integers + + + An integer is a number of the set + Z = {..., -2, -1, 0, 1, 2, ...}. + + + + See also: + Arbitrary precision integers and + Floating point numbers + + + + Syntax + + Integers can be specified in decimal (10-based), hexadecimal (16-based) + or octal (8-based) notation, optionally preceded by a sign (- or +). + + + If you use the octal notation, you must precede the number with a + 0 (zero), to use hexadecimal notation precede + the number with 0x. + + Integer literals + $a = 1234; # decimal number $a = -123; # a negative number $a = 0123; # octal number (equivalent to 83 decimal) -$a = 0x12; # hexadecimal number (equivalent to 18 decimal) - - - The size of an integer is platform-dependent, although a - maximum value of about 2 billion is the usual value - (that's 32 bits signed). - +$a = 0x1A; # hexadecimal number (equivalent to 26 decimal) + + + + 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). + + + + In PHP there is no such thing as integer-division. 1/2 + yields the double 0.5. + + + Integer overflow - Because of the flexible type-juggling, a number - is autmatically converted to float when it is about - to overflow. + If you specify a number beyond the bounds of the integer-type, + it will be interpreted as a double instead. + + +$large_number = 2147483647; +var_dump($large_number); +// output: int(2147483647) +$large_number = 2147483648; +var_dump($large_number); +// output: float(2147483648) + + + Furthermore, if some function or operator yields a number that is beyond + the boundaries of integer, it will also + be automatically converted to + double. + + +$million = 1000000; +$large_number = 50000 * $million; +var_dump($large_number); +// output: float(50000000000) + + @@ -222,21 +341,27 @@ $a = 0x12; # hexadecimal number (equivalent to 18 decimal) Converting to integer - See type-juggling for - general information about converting. + To explicitely convert a value to integer, use either + the (int) or the (integer) cast. + However, in most cases you do not need to use the cast, since a value + will be autmatically converted if an operator, function or + control-structure requires a boolean-argument. + + + See also type-juggling. From <link linkend="language.types.boolean" >booleans</link> - False will yield - 0 (zero), and True - will yield 1 (one). + FALSE will yield + 0 (zero), and TRUE + will yield 1 (one). - + From floating point numbers When converting from float to integer, the number will @@ -249,20 +374,18 @@ $a = 0x12; # hexadecimal number (equivalent to 18 decimal) (usually +/- 2.15e+9 = 2^31), 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! - - + No warning, not even a notice will be issued in this + case! Never cast an unknown fraction to integer, as this can sometimes lead to unexpected results. - + + echo (int) ( (0.1+0.7) * 10 ); // echo's 7! - + + See for more information the warning @@ -276,26 +399,43 @@ echo (int) ( (0.1+0.7) * 10 ); // echo's 7! See String conversion - - - See also: - Arbitrary precision integers and - Floating point numbers - + + + From other types + + Behaviour of converting to integer is undefined for other + types. Currently, the behaviour is the same as if + the value was first converted to boolean. + + + However, do not + relay on this behaviour, as it can change without notice. + + + + + + Floating point numbers - Floating point numbers (aka "doubles" or "real numbers") can be + Floating point numbers (aka "doubles", "floats" or "real numbers") can be specified using any of the following syntaxes: - - + $a = 1.234; $a = 1.2e3; $a = 7E-10; - - + + collection, + stack, queue and probably more. Because you can have another + PHP-array as a value, you can also quite easily simulate + trees. + + Explaination of those structures is beyond the scope of this manual, + but you'll find at least one example for each of those structures. + For more information about those structures, buy a good book about + datastructures. + + + + + Syntax + + + Specifying with <function>array</function> + + An array can be created by the array + language-construct. It takes a certain number of comma-separated + key => value + pairs. + + + A key is either a nonnegative integer + + or a string. + If a key is the standard representation of a non-negative + integer, it will + be interpreted as such (i.e. '8' will be interpreted + as 8, while + '08' will be interpreted as '08'). + + + A value can be anything. + + + Omitting keys + + If you omit a key, the maximum of the integer-indices is taken, and + the new key will be that maximum + 1. If no integer-indices yet + exist, the key will be 0 (zero). If you specify a key + that already has a value assigned to, that key will be overwritten. + + + + + +array( key => value + , ... + ) +// key is either string or nonnegative integer +// value can be anything + + + + + + Creating/modifying with square-bracket syntax + + You can also modify an existing array, by explicitely setting + values. + + + This is done by assigning values to the array while specifying the + key in brackets. You can also + omit the key, + add an empty pair + of brackets ("[]") to the variable-name in that case. + +$arr[key] = value; +$arr[] = value; +// key is either string or nonnegative integer +// value can be anything + + If $arr doesn't yet exist, it will be created. + So this is also + an alternative way to specify an array. + To change a certain value, just assign a new value + to it. + If you want to remove a key/value pair, you need to + unset it. + + + + + + + + + Useful functions + + There are quite some useful function for working + with arrays, see the array-functions + section. + + + The foreach + control-structure exists specificly for arrays. It + provides an easy way to traverse an array. + + + + + Examples + + The array-type in PHP is very versatile, so here will be some + examples to show you the full power of arrays. + + + + +// this +$a = array( 'color' => 'red' + , 'taste' => 'sweet', + , 'shape' => 'round', + , 'name' => 'apple', + , 4 // key will be 0 + ); + +// is completely equivalent with +$a['color'] = 'red'; +$a['taste'] = 'sweet'; +$a['shape'] = 'round'; +$a[] = 4; // key will be 0 + +$b[] = 'a'; +$b[] = 'b'; +$b[] = 'c'; +// will result in the array array( 0 => 'a' , 1 => 'b' , 2 => 'c' ) + + + + + + Using array() + +// Array as (property-)map +$map = array( 'version' => 4 + , 'OS' => 'Linux' + , 'lang' => 'english' + , 'short_tags' => true + ); + +// strictly numerical keys +$array = array( 7 + , 8 + , 0 + , 156 + , -10 + ); +// this is the same as array( 0 => 7, 1 => 8, ...) + +$switching = array( 10 // key = 0 + , 5 => 6 + , 3 => 7 + , 'a' => 4 + , 11 // key = 6 (maximum of integer-indices was 5) + , '8' => 2 // key = 8 (integer!) + , '02' => 77 // key = '02' + , 0 => 12 // the value 10 will be overwritten by 12 + ); + + + +// empty array +$empty = array(); + + + + + Collection + +$colors = array('red','blue','green','yellow'); + +foreach ( $colors as $color ) +{ + echo "Do you like $color?\n"; +} + +/* output: +Do you like red? +Do you like blue? +Do you like green? +Do you like yellow? +*/ + + + + + Note that it is currently not possible to change the values of the array + directly in such a loop. + + A workaround is the following: + + Collection + +foreach ( $colors as $key => $color ) +{ + // won't work: + //$color = strtoupper($color); + + //works: + $colors[$key] = strtoupper($color); +} +print_r($colors); + +/* output: +Array +( + [0] => RED + [1] => BLUE + [2] => GREEN + [3] => YELLOW +) +*/ + + + + + This example creates a one-based array. + + One-based index + +$firstquarter = array(1 => 'January', 'February', 'March'); +print_r($firstquarter); + +/* output: +Array +( + [1] => 'January' + [2] => 'February' + [3] => 'March' +) +*/ + + + + + Filling real array + +// fill an array with all items from a directory +$handle = opendir('.'); +while ( $file = readdir($handle) ) +{ + $files[] = $file; +} +closedir($handle); + + + + Arrays are ordered. You can also change the order using differen + sorting-functions. See array-functions + for more information. + + + Sorting array + +sort($files); +print_r($files); + + + + Because the value of an array can be everything, it can also be + another array. This way you can make recursive arrays, and + multi-dimensional arrays. + + + Recursive and multi-dimensional arrays + +$fruits = array ( "fruits" => array ( "a" => "orange" + , "b" => "banana" + , "c" => "apple" + ) + , "numbers" => array ( 1 + , 2 + , 3 + , 4 + , 5 + , 6 + ) + , "holes" => array ( "first" + , 5 => "second" + , "third" + ) + ); + + + + + + + + + + @@ -936,6 +1458,7 @@ $bar->do_foo(); + @@ -944,11 +1467,29 @@ $bar->do_foo(); Null + + The special NULL value represents + that a variable has no value. + The null-type was introduced in PHP 4 + + + Syntax + + There is only one value of type null, and that is + the case-insensitive keyword + NULL. + + +$var = Null; + + + + @@ -975,11 +1516,31 @@ $bar->do_foo(); $foo = "0"; // $foo is string (ASCII 48) + +$foo += 2; // $foo is now an integer (2) $foo = $foo + 1.3; // $foo is now a double (3.3) $foo = 5 + "10 Little Piggies"; // $foo is integer (15) $foo = 5 + "10 Small Pigs"; // $foo is integer (15) + @@ -996,13 +1557,7 @@ $foo = 5 + "10 Small Pigs"; // $foo is integer (15) If you would like to test any of the examples in this section, you - can cut and paste the examples and insert the following line to - see for yourself what's going on: - - -echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n"; - - + can use the var_dump function. @@ -1076,6 +1631,14 @@ $bar = (double) $foo; // $bar is a double + + + Instead of casting a variable to string, you can also use enclose + the variable in double quotes. + + + + Note that tabs and spaces are allowed inside the parentheses, so the following are functionally equivalent: