From 5b09b299d6e0a2bc4a5c0996a3e2e8dd7019cf5d Mon Sep 17 00:00:00 2001 From: Gwynne Raskind Date: Thu, 14 Feb 2008 19:57:17 +0000 Subject: [PATCH] step one of updating language.types: split into separate files (types.xml) was getting too big git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@252927 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/types.xml | 2571 +----------------------------- language/types/array.xml | 858 ++++++++++ language/types/boolean.xml | 168 ++ language/types/float.xml | 95 ++ language/types/integer.xml | 261 +++ language/types/null.xml | 77 + language/types/object.xml | 83 + language/types/psuedo-types.xml | 167 ++ language/types/resource.xml | 81 + language/types/string.xml | 729 +++++++++ language/types/type-juggling.xml | 261 +++ 11 files changed, 2791 insertions(+), 2560 deletions(-) create mode 100644 language/types/array.xml create mode 100644 language/types/boolean.xml create mode 100644 language/types/float.xml create mode 100644 language/types/integer.xml create mode 100644 language/types/null.xml create mode 100644 language/types/object.xml create mode 100644 language/types/psuedo-types.xml create mode 100644 language/types/resource.xml create mode 100644 language/types/string.xml create mode 100644 language/types/type-juggling.xml diff --git a/language/types.xml b/language/types.xml index be55f4a72d..5db9a34bd5 100644 --- a/language/types.xml +++ b/language/types.xml @@ -1,5 +1,5 @@ - + Types @@ -171,2567 +171,18 @@ if (is_string($a_bool)) { as they show examples of various type related comparisons. - - - Booleans - - - This is the easiest type. A boolean expresses a - truth value. It can be either &true; or &false;. - - - - - 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. - - - -]]> - - - - - Usually you - use some kind of operator - which returns a boolean value, and then pass it - on to a control - structure. - - -\n"; -} - -// ...because you can simply type -if ($show_separators) { - echo "
\n"; -} -?> -]]> - - - - - - - Converting to boolean - - To explicitly 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 automatically 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;: - - - - the boolean - &false; itself - - - the integer 0 (zero) - - - the float - 0.0 (zero) - - - the empty string, and the string - "0" - - - an array - with zero elements - - - an object - with zero member variables (PHP 4 only) - - - the special type NULL (including unset variables) - - - - SimpleXML - objects created from empty tags - - - - - Every other value is considered &true; (including any - resource). - - - -1 is considered - &true;, like any other non-zero (whether negative - or positive) number! - - - - - -]]> - - - - - - - - Integers - - - An integer is a number of the set - Z = {..., -2, -1, 0, 1, 2, ...}. - - - - See also: - Arbitrary length integer / GMP, - Floating point numbers, and - Arbitrary precision / BCMath - - - - 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 - - -]]> - - - Formally the possible structure for integer literals is: - - - - - - 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 PHP_INT_SIZE, - maximum value from PHP_INT_MAX since PHP 4.4.0 and - PHP 5.0.5. - - - - If an invalid digit is passed to octal integer (i.e. 8 or 9), the rest - of the number is ignored. - - Octal weirdness - - -]]> - - - - - - - - Integer overflow - - If you specify a number beyond the bounds of the integer - type, it will be interpreted as a float instead. Also, if - you perform an operation that results in a number beyond the bounds of - the integer type, a float will be returned - instead. - - - - -]]> - - - - - 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 -50000 * - $million, the result will be - -429496728. However, when both operands are - positive there is no problem. - - - This is solved in PHP 4.1.0. - - - - - There is no integer division operator in PHP. - 1/2 yields the float - 0.5. You can cast the value to - an integer to always round it downwards, or you can - use the round function. - - - -]]> - - - - - - - - Converting to integer - - To explicitly 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 automatically converted if an operator, function or - control structure requires an integer argument. - You can also convert a value to integer with the function - intval. - - - See also type-juggling. - - - - From <link linkend="language.types.boolean" - >booleans</link> - - &false; will yield - 0 (zero), and &true; - will yield 1 (one). - - - - - From <link linkend="language.types.float">floating point numbers</link> - - When converting from float to integer, the number will - be rounded towards zero. - - - - If the float is beyond the boundaries of integer - (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! - - - - Never cast an unknown fraction to integer, as this can - sometimes lead to unexpected results. - - - -]]> - - - - See for more information the warning - about float-precision. - - - - - From strings - - See String - conversion to 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 rely on this behaviour, as it can - change without notice. - - - - - - - - - Floating point numbers - - Floating point numbers (AKA "floats", "doubles" or "real numbers") can be - specified using any of the following syntaxes: - - - -]]> - - - Formally: - - - - - - 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). - - - Floating point precision - - It is quite usual that simple decimal fractions like - 0.1 or 0.7 cannot be - converted into their internal binary counterparts without a - little loss of precision. This can lead to confusing results: for - example, floor((0.1+0.7)*10) will usually - return 7 instead of the expected - 8 as the result of the internal representation - really being something like 7.9999999999.... - - - 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, 1/3 in decimal form - becomes 0.3333333. . .. - - - 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 arbitrary precision math functions - or gmp functions instead. - - - - - Converting to float - - - For information on when and how strings are converted to floats, - see the section titled String - conversion to numbers. 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 Converting - to integer section for more information. - As of PHP 5, notice is thrown if you try to convert object to float. - - - - - - Strings - - A string 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. See utf8_encode - and utf8_decode for some Unicode support. - - - - It is no problem for a string to become very large. - There is no practical bound to the size - of strings imposed by PHP, so there is no reason at all - to worry about long strings. - - - - Syntax - - A string literal can be specified in three different - ways. - - - - - single quoted - - - - - double quoted - - - - - heredoc syntax - - - - - - - Single quoted - - The easiest way to specify a simple string is to - enclose it in single quotes (the character '). - - - To specify a literal single - quote, you will need to escape it with a backslash - (\), 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 will also be printed! So - usually there is no need to escape the backslash itself. - - - In PHP 3, a warning will - be issued at the E_NOTICE level when this - happens. - - - - - Unlike the two other syntaxes, variables and escape sequences - for special characters will not be expanded - when they occur in single quoted strings. - - - - - -]]> - - - - - - Double quoted - - If the string is enclosed in double-quotes ("), - PHP understands more escape sequences for special - characters: - - - Escaped characters - - - - sequence - meaning - - - - - \n - linefeed (LF or 0x0A (10) in ASCII) - - - \r - carriage return (CR or 0x0D (13) in ASCII) - - - \t - horizontal tab (HT or 0x09 (9) in ASCII) - - - \v - vertical tab (VT or 0x0B (11) in ASCII) (since PHP 5.2.5) - - - \f - form feed (FF or 0x0C (12) in ASCII) (since PHP 5.2.5) - - - \\ - backslash - - - \$ - dollar sign - - - \" - double-quote - - - \[0-7]{1,3} - - the sequence of characters matching the regular - expression is a character in octal notation - - - - \x[0-9A-Fa-f]{1,2} - - the sequence of characters matching the regular - expression is a character in hexadecimal notation - - - - -
- - Again, if you try to escape any other character, the - backslash will be printed too! - Before PHP 5.1.1, backslash in \{$var} hasn't been - printed. - - - But the most important feature of double-quoted strings - is the fact that variable names will be expanded. - See string - parsing for details. - - - - - Heredoc - - Another way to delimit strings is by using heredoc syntax - ("<<<"). One should provide an identifier (followed by new line) after - <<<, then the string, and then the - same identifier to close the quotation. - - - The closing identifier must begin in the - 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. - - - - - It is very important to note that the line with the closing - identifier contains no other characters, except - possibly a semicolon (;). - That means especially that the identifier - may not be indented, and there - may not be any spaces or tabs after or before the semicolon. - It's also important to realize that the first character before - the closing identifier must be a newline as defined by your - operating system. This is \r on Macintosh - for example. Closing delimiter (possibly followed by a semicolon) must - be followed by a newline too. - - - If this rule is broken and the closing identifier is not "clean" - then it's not considered to be a closing identifier and PHP - will continue looking for one. If in this case a proper closing - identifier is not found then a parse error will result with the - line number being at the end of the script. - - - It is not allowed to use heredoc syntax in initializing class members. - Use other string syntaxes instead. - - Invalid example - - -]]> - - - - - - - Heredoc text behaves just like a double-quoted string, without - the double-quotes. This means that you do not need to escape quotes - in your here docs, but you can still use the escape codes listed - above. Variables are expanded, but the same care must be taken - when expressing complex variables inside a heredoc as with - strings. - - Heredoc string quoting example - -foo = 'Foo'; - $this->bar = array('Bar1', 'Bar2', 'Bar3'); - } -} - -$foo = new foo(); -$name = 'MyName'; - -echo <<foo. -Now, I am printing some {$foo->bar[1]}. -This should print a capital 'A': \x41 -EOT; -?> -]]> - - - - - - - Heredoc support was added in PHP 4. - - - - - - Variable parsing - - When a string is specified in double quotes or with - heredoc, variables are - parsed within it. - - - There are two types of syntax: a - simple - one and a - complex - one. - The simple syntax is the most common and convenient. It provides a way - to parse a variable, an array value, or an - object property. - - - The complex syntax was introduced in PHP 4, and can be recognised - by the curly braces surrounding the expression. - - - - Simple syntax - - If a dollar sign ($) is encountered, the - parser will greedily take as many tokens as possible to form a - valid variable name. Enclose the variable name in curly - braces if you want to explicitly specify the end of the name. - - - - -]]> - - - - Similarly, you can also have an array index or an - object property parsed. With array indices, the closing square - bracket (]) marks the end of the index. For - object properties the same rules apply as to simple variables, - though with object properties there doesn't exist a trick like - the one with variables. - - - - - - - 'red', 'banana' => 'yellow'); - -// Works but note that this works differently outside string-quotes -echo "A banana is $fruits[banana]."; - -// Works -echo "A banana is {$fruits['banana']}."; - -// Works but PHP looks for a constant named banana first -// as described below. -echo "A banana is {$fruits[banana]}."; - -// Won't work, use braces. This results in a parse error. -echo "A banana is $fruits['banana']."; - -// Works -echo "A banana is " . $fruits['banana'] . "."; - -// Works -echo "This square is $square->width meters broad."; - -// Won't work. For a solution, see the complex syntax. -echo "This square is $square->width00 centimeters broad."; -?> -]]> - - - - - For anything more complex, you should use the complex syntax. - - - - - Complex (curly) syntax - - This isn't called complex because the syntax is complex, - but because you can include complex expressions this way. - - - In fact, you can include any value that is in the namespace - in strings with this syntax. You simply write the expression - 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 "{$"). - Some examples to make it clear: - - - -width}00 centimeters broad."; - -// Works -echo "This works: {$arr[4][3]}"; - -// This is wrong for the same reason as $foo[bar] is wrong -// outside a string. In other words, it will still work but -// because PHP first looks for a constant named foo, it will -// throw an error of level E_NOTICE (undefined constant). -echo "This is wrong: {$arr[foo][3]}"; - -// Works. When using multi-dimensional arrays, always use -// braces around arrays when inside of strings -echo "This works: {$arr['foo'][3]}"; - -// Works. -echo "This works: " . $arr['foo'][3]; - -echo "You can even write {$obj->values[3]->name}"; - -echo "This is the value of the var named $name: {${$name}}"; - -echo "This is the value of the var named by the return value of getName(): {${getName()}}"; - -echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}"; -?> -]]> - - - - - - - Functions and method calls inside {$ } work since PHP 5. - - - - - Parsing variables within strings uses more memory than string - concatenation. When writing a PHP script in which memory usage is a - concern, consider using the concatenation operator (.) rather than - variable parsing. - - - - - - - String access and modification by character - - Characters within strings may be accessed and modified by specifying the - zero-based offset of the desired character after the string - using square array-brackets like $str[42] so think of - a string as an array of characters. - - - - They may also be accessed using braces like $str{42} - for the same purpose. However, using square array-brackets is preferred - because the {braces} style is deprecated as of PHP 6. - - - - - Some string examples - - -]]> - - - - - - Accessing by [] or {} to - variables of other type silently returns &null;. - - - - - - - - Useful functions and operators - - Strings may be concatenated using the '.' (dot) operator. Note - that the '+' (addition) operator will not work for this. Please - see String - operators for more information. - - - There are a lot of useful functions for string modification. - - - See the string functions section - for general functions, the regular expression functions for - advanced find&replacing (in two tastes: - Perl and - POSIX extended). - - - There are also functions for URL-strings, - and functions to encrypt/decrypt strings - (mcrypt and - mhash). - - - Finally, if you still didn't find what you're looking for, - see also the character type functions. - - - - - Converting to string - - - You can convert a value to a string using the (string) - cast, or the strval function. String conversion - is automatically done in the scope of an expression for you where a - string is needed. This happens when you use the echo - or print functions, or when you compare a variable - value to a string. Reading the manual sections on Types and Type Juggling will make - the following clearer. See also settype. - - - - A boolean &true; value is converted to the string "1", - the &false; value is represented as "" (empty string). - This way you can convert back and forth between boolean and string values. - - - An integer or a floating point number (float) - is converted to a string representing the number with its digits - (including the exponent part for floating point numbers). - Floating point numbers can be converted using the exponential notation - (4.1E+6). - - - - The decimal point character is defined in the script's - locale (category LC_NUMERIC). - See setlocale. - - - - Arrays are always converted to the string "Array", - so you cannot dump out the contents of an array with - echo or print to see what is inside - them. To view one element, you'd do something like - echo $arr['foo']. See below for tips on dumping/viewing the - entire contents. - - - Objects in PHP 4 are always converted to the string "Object". - If you would like to print out the member variable values of an - object for debugging reasons, read the paragraphs - below. If you would like to find out the class name of which an object - is an instance of, use get_class. - As of PHP 5, __toString() method is used if applicable. - - - Resources are always converted to strings with the structure - "Resource id #1" where 1 is - the unique number of the resource assigned by PHP during runtime. - If you would like to get the type of the resource, use - get_resource_type. - - - &null; is always converted to an empty string. - - - - As you can see above, printing out the arrays, objects or resources does not - provide you any useful information about the values themselves. Look at the - functions print_r and var_dump - for better ways to print out values for debugging. - - - - You can also convert PHP values to strings to store them permanently. This - method is called serialization, and can be done with the function - serialize. You can also serialize PHP values to - XML structures, if you have WDDX support - in your PHP setup. - - - - - String conversion to numbers - - - When a string is evaluated as a numeric value, the resulting - value and type are determined as follows. - - - The string will evaluate as a float if it contains any of the - characters '.', 'e', or 'E'. Otherwise, it will evaluate as an - integer. - - - The value is given by the initial portion of the string. If the - string starts with valid numeric data, this will be the value - used. Otherwise, the value will be 0 (zero). Valid numeric data - is an optional sign, followed by one or more digits (optionally - containing a decimal point), followed by an optional - exponent. The exponent is an 'e' or 'E' followed by one or more - digits. - - - - -]]> - - - - For more information on this conversion, see the Unix manual page - for strtod(3). - - - 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: - - -\n"; -?> -]]> - - - - - Do not expect to get the code of one character by converting it - to integer (as you would do in C for example). Use the functions - ord and chr to convert - between charcodes and characters. - - - - - - - Arrays - - - An array in PHP is actually an ordered map. A map is a type that - maps values to keys. - This type is optimized in several ways, - so you can use it as a real array, or a list (vector), - hashtable (which is an implementation of a map), - dictionary, collection, - stack, queue and probably more. Because you can have another - PHP array as a value, you can also quite easily simulate - trees. - - - Explanation of those data structures is beyond the scope of this - manual, but you'll find at least one example for each of them. - For more information we refer you to external literature about - this broad topic. - - - - 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. - - - -array( key => value - , ... - ) -// key may be an integer or string -// value may be any value - - - - - - "bar", 12 => true); - -echo $arr["foo"]; // bar -echo $arr[12]; // 1 -?> -]]> - - - - - A key may be either an - integer or a string. If a key is - the standard representation of an integer, it will - be interpreted as such (i.e. "8" will be - interpreted as 8, while - "08" will be interpreted as - "08"). - Floats in key are truncated to integer. - There are no different indexed and - associative array types in PHP; there is only one array type, - which can both contain integer and string indices. - - - A value can be of any PHP type. - - - array(6 => 5, 13 => 9, "a" => 42)); - -echo $arr["somearray"][6]; // 5 -echo $arr["somearray"][13]; // 9 -echo $arr["somearray"]["a"]; // 42 -?> -]]> - - - - - If you do not specify a key for a given value, then the maximum - of the integer indices is taken, and the new key will be that - maximum value + 1. If you specify a key that already has a value - assigned to it, that value will be overwritten. - - - 43, 32, 56, "b" => 12); - -// ...this array -array(5 => 43, 6 => 32, 7 => 56, "b" => 12); -?> -]]> - - - - - - As of PHP 4.3.0, the index generation behaviour described - above has changed. Now, if you append to an array in which - the current maximum key is negative, then the next key - created will be zero (0). Before, the new - index would have been set to the largest existing key + 1, - the same as positive indices are. - - - - Using &true; as a key will evaluate to integer - 1 as key. Using &false; as a key will evaluate - to integer 0 as key. Using - NULL as a key will evaluate to the empty - string. Using the empty string as key will create (or overwrite) - a key with the empty string and its value; it is not the same as - using empty brackets. - - - You cannot use arrays or objects as keys. Doing so will result in a - warning: Illegal offset type. - - - - - Creating/modifying with square-bracket syntax - - You can also modify an existing array by explicitly setting - values in it. - - - 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 may be an integer or string -// value may be any value - - If $arr doesn't exist yet, 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 an element specified with its key. If you want to - remove a key/value pair, you need to unset it. - - - 1, 12 => 2); - -$arr[] = 56; // This is the same as $arr[13] = 56; - // at this point of the script - -$arr["x"] = 42; // This adds a new element to - // the array with key "x" - -unset($arr[5]); // This removes the element from the array - -unset($arr); // This deletes the whole array -?> -]]> - - - - - - As mentioned above, if you provide the brackets with no key - specified, then the maximum of the existing integer indices is - taken, and the new key will be that maximum value + 1 . If no - integer indices exist yet, the key will be 0 - (zero). If you specify a key that already has a value assigned - to it, that value will be overwritten. - - - - - As of PHP 4.3.0, the index generation behaviour described - above has changed. Now, if you append to an array in which - the current maximum key is negative, then the next key - created will be zero (0). Before, the new - index would have been set to the largest existing key + 1, - the same as positive indices are. - - - - - Note that the maximum integer key used for this need - not currently exist in the array. It simply must - have existed in the array at some time since the last time the - array was re-indexed. The following example illustrates: - - - - - $value) { - unset($array[$i]); -} -print_r($array); - -// Append an item (note that the new key is 5, instead of 0 as you -// might expect). -$array[] = 6; -print_r($array); - -// Re-index: -$array = array_values($array); -$array[] = 7; -print_r($array); -?> -]]> - - &example.outputs; - - 1 - [1] => 2 - [2] => 3 - [3] => 4 - [4] => 5 -) -Array -( -) -Array -( - [5] => 6 -) -Array -( - [0] => 6 - [1] => 7 -) -]]> - - - - - - - - - Useful functions - - There are quite a few useful functions for working with arrays. - See the array functions section. - - - - The unset function allows unsetting keys of an - array. Be aware that the array will NOT be reindexed. If you only - use "usual integer indices" (starting from zero, increasing by one), - you can achieve the reindex effect by using array_values. - - - 'one', 2 => 'two', 3 => 'three'); -unset($a[2]); -/* will produce an array that would have been defined as - $a = array(1 => 'one', 3 => 'three'); - and NOT - $a = array(1 => 'one', 2 =>'three'); -*/ - -$b = array_values($a); -// Now $b is array(0 => 'one', 1 =>'three') -?> -]]> - - - - - - - The foreach - control structure exists specifically for arrays. It - provides an easy way to traverse an array. - - - - - Array do's and don'ts - - - Why is <literal>$foo[bar]</literal> wrong? - - You should always use quotes around a string literal - array index. For example, use $foo['bar'] and not - $foo[bar]. But why is $foo[bar] wrong? You might have seen the - following syntax in old scripts: - - - -]]> - - - This is wrong, but it works. Then, why is it wrong? The reason - is that this code has an undefined constant (bar) rather than a - string ('bar' - notice the quotes), and PHP may in future define - constants which, unfortunately for your code, have the same - name. It works because PHP automatically converts a - bare string (an unquoted string which does - not correspond to any known symbol) into a string which contains - the bare string. For instance, if there is no defined constant - named bar, then PHP will substitute in the - string 'bar' and use that. - - - - This does not mean to always quote the - key. You do not want to quote keys which are constants or variables, as this will - prevent PHP from interpreting them. - - - - -]]> - - - &example.outputs; - - - - - - More examples to demonstrate this fact: - - - 'apple', 'veggie' => 'carrot'); - -// Correct -print $arr['fruit']; // apple -print $arr['veggie']; // carrot - -// Incorrect. This works but also throws a PHP error of -// level E_NOTICE because of an undefined constant named fruit -// -// Notice: Use of undefined constant fruit - assumed 'fruit' in... -print $arr[fruit]; // apple - -// Let's define a constant to demonstrate what's going on. We -// will assign value 'veggie' to a constant named fruit. -define('fruit', 'veggie'); - -// Notice the difference now -print $arr['fruit']; // apple -print $arr[fruit]; // carrot - -// The following is okay as it's inside a string. Constants are not -// looked for within strings so no E_NOTICE error here -print "Hello $arr[fruit]"; // Hello apple - -// With one exception, braces surrounding arrays within strings -// allows constants to be looked for -print "Hello {$arr[fruit]}"; // Hello carrot -print "Hello {$arr['fruit']}"; // Hello apple - -// This will not work, results in a parse error such as: -// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING' -// This of course applies to using superglobals in strings as well -print "Hello $arr['fruit']"; -print "Hello $_GET['foo']"; - -// Concatenation is another option -print "Hello " . $arr['fruit']; // Hello apple -?> -]]> - - - - - When you turn error_reporting up to show - E_NOTICE level errors (such as setting - it to E_ALL) then you will see these - errors. By default, - error_reporting is turned down to not show them. - - - As stated in the syntax section, - there must be an expression between the square brackets - ('[' and ']'). That means - that you can write things like this: - - - -]]> - - - This is an example of using a function return value - as the array index. PHP also knows about constants, - as you may have seen the E_* ones - before. - - - - -]]> - - - Note that E_ERROR is also a valid identifier, - just like bar in the first example. But the last - example is in fact the same as writing: - - - -]]> - - - because E_ERROR equals 1, etc. - - - As we already explained in the above examples, - $foo[bar] still works but is wrong. - It works, because bar is due to its syntax - expected to be a constant expression. However, in this case no - constant with the name bar exists. PHP now - assumes that you meant bar literally, - as the string "bar", but that you forgot - to write the quotes. - - - So why is it bad then? - - At some point in the future, the PHP team might want to add another - constant or keyword, or you may introduce another constant into your - application, and then you get in trouble. For example, - you already cannot use the words empty and - default this way, since they are special - reserved keywords. - - - - To reiterate, inside a double-quoted string, it's - valid to not surround array indexes with quotes so - "$foo[bar]" is valid. See the above - examples for details on why as well as the section on - variable parsing - in strings. - - - - - - - - Converting to array - - - For any of the types: integer, float, - string, boolean and resource, - if you convert a value to an array, you get an array - with one element (with index 0), which is the scalar value you - started with. - - - - If you convert an object to an array, you get the - properties (member variables) of that object as the array's elements. - The keys are the member variable names with a few notable exceptions: - private variables have the class name prepended to the variable name; - protected variables have a '*' prepended to the variable name. - These prepended values have null bytes on either side. This can result - in some unexpected behaviour. - - - -]]> - - - - The above will appear to have two keys named 'AA', although one - of them is actually named '\0A\0A'. - - - - If you convert a &null; value to an array, you get an empty array. - - - - - Comparing - - It is possible to compare arrays by array_diff and - by Array operators. - - - - - Examples - - The array type in PHP is very versatile, so here will be some - examples to show you the full power of arrays. - - - - - '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['name'] = 'apple'; -$a[] = 4; // key will be 0 - -$b[] = 'a'; -$b[] = 'b'; -$b[] = 'c'; -// will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'), -// or simply array('a', 'b', 'c') -?> -]]> - - - - - - Using array() - - 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 - - -]]> - - &example.outputs; - - - - - - - Changing values of the array directly is possible since PHP 5 by passing - them as reference. Prior versions need workaround: - - Collection - - $color) { - $colors[$key] = strtoupper($color); -} - -print_r($colors); -?> -]]> - - &example.outputs; - - RED - [1] => BLUE - [2] => GREEN - [3] => YELLOW -) -]]> - - - - - This example creates a one-based array. - - One-based index - - 'January', 'February', 'March'); -print_r($firstquarter); -?> -]]> - - &example.outputs; - - 'January' - [2] => 'February' - [3] => 'March' -) -]]> - - - - - Filling an array - - -]]> - - - - Arrays are ordered. You can also change the order using various - sorting functions. See the array - functions section for more information. You can count - the number of items in an array using the - count function. - - - Sorting an array - - -]]> - - - - Because the value of an array can be anything, it can also be - another array. This way you can make recursive and - multi-dimensional arrays. - - - Recursive and multi-dimensional arrays - - array ( "a" => "orange", - "b" => "banana", - "c" => "apple" - ), - "numbers" => array ( 1, - 2, - 3, - 4, - 5, - 6 - ), - "holes" => array ( "first", - 5 => "second", - "third" - ) - ); - -// Some examples to address values in the array above -echo $fruits["holes"][5]; // prints "second" -echo $fruits["fruits"]["a"]; // prints "orange" -unset($fruits["holes"][0]); // remove "first" - -// Create a new multi-dimensional array -$juices["apple"]["green"] = "good"; -?> -]]> - - - - You should be aware that array assignment always involves - value copying. It also means that the internal array pointer used by - current and similar functions is reset. - You need to use the reference operator to copy - an array by reference. - - - -]]> - - - - - - - - Objects - - - Object Initialization - - - To initialize an object, you use the new - statement to instantiate the object to a variable. - - - -do_foo(); -?> -]]> - - - - - For a full discussion, please read the section Classes and Objects. - - - - - Converting to object - - - 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 - stdClass 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 scalar will - contain the value. - - -scalar; // outputs 'ciao' -?> -]]> - - - - - - - - - Resource - - - A resource is a special variable, holding - a reference to an external resource. Resources - are created and used by special functions. - See the appendix - for a listing of all these - functions and the corresponding resource types. - - - - - The resource type was introduced in PHP 4 - - - - - See also get_resource_type. - - - - Converting to resource - - - 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. - - - - - Freeing resources - - - 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. - - - Persistent database links are special, they - are not destroyed by the - garbage collector. See also the section about persistent - connections. - - - - - - - - - NULL - - - The special &null; value represents - that a variable has no value. &null; is the only possible value of type - NULL. - - - - The null type was introduced in PHP 4. - - - - A variable is considered to be &null; if - - - - it has been assigned the constant &null;. - - - - - it has not been set to any value yet. - - - - - it has been unset. - - - - - - - Syntax - - There is only one value of type &null;, and that is - the case-insensitive keyword &null;. - - - -]]> - - - - - See also is_null and unset. - - - + &language.types.boolean; + &language.types.integer; + &language.types.float; + &language.types.string; + &language.types.array; + &language.types.object; + &language.types.resource; + &language.types.null; + &language.types.psuedo-types; + &language.types.type-juggling; - - Pseudo-types and variables used in this documentation - - - mixed - - mixed indicates that a parameter may accept multiple (but not - necessarily all) types. - - - gettype for example will accept all PHP types, - while str_replace will accept strings and arrays. - - - - - number - - number indicates that a parameter can be either - integer or float. - - - - - callback - - Some functions like call_user_func - or usort accept user defined - callback functions as a parameter. Callback functions can not only - be simple functions but also object methods including static class - methods. - - - 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 - array, - echo, - empty, - eval, - exit, - isset, - list, - print or - unset cannot be called using a callback. - - - 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. - - - 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. - - - Apart from common user-defined function, - create_function can be used to create an anonymous - callback function. - - - - - - Callback function examples - - - -]]> - - - - - - 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 References Explained. - - - - - - - void - - void in return type means that the return value is - useless. void in parameters list means that the - function doesn't accept any parameters. - - - - - ... - - $... in function prototypes means - and so on. - This variable name is used when a function can take an endless number of - arguments. - - - - - - Type Juggling - - - 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 $var, - $var becomes a string. If you then assign an - integer value to $var, it becomes an - integer. - - - 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. - - - -]]> - - - - - - If the last two examples above seem odd, see String - conversion to numbers. - - - If you wish to force a variable to be evaluated as a certain type, - see the section on Type - casting. If you wish to change the type of a variable, see - settype. - - - If you would like to test any of the examples in this section, you - can use the var_dump function. - - - - The behaviour of an automatic conversion to array is currently - undefined. - - - 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: - - - -]]> - - - - - See the section titled String - access by character for more information. - - - - - Type Casting - - - 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. - - - -]]> - - - - - The casts allowed are: - - - (int), (integer) - cast to integer - - - (bool), (boolean) - cast to boolean - - - (float), (double), (real) - cast to float - - - (string) - cast to string - - - (binary) - cast to binary string (PHP 6) - - - (array) - cast to array - - - (object) - cast to object - - - - - (binary) casting and b prefix forward support was added in PHP 5.2.1 - - - Note that tabs and spaces are allowed inside the parentheses, so - the following are functionally equivalent: - - - -]]> - - - Casting a literal strings and variables to binary strings: - - - -]]> - - - - - - Instead of casting a variable to string, you can also enclose - the variable in double quotes. - - - -]]> - - - - - - - It may not be obvious exactly what will happen when casting - between certain types. For more info, see these sections: - - - - Converting to - boolean - - - Converting to - integer - - - Converting to - float - - - Converting to - string - - - Converting to - array - - - Converting to - object - - - Converting to - resource - - - - - The type comparison tables - - - - - - - + + Arrays + + + An array in PHP is actually an ordered map. A map is a type that + maps values to keys. + This type is optimized in several ways, + so you can use it as a real array, or a list (vector), + hashtable (which is an implementation of a map), + dictionary, collection, + stack, queue and probably more. Because you can have another + PHP array as a value, you can also quite easily simulate + trees. + + + Explanation of those data structures is beyond the scope of this + manual, but you'll find at least one example for each of them. + For more information we refer you to external literature about + this broad topic. + + + + 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. + + + +array( key => value + , ... + ) +// key may be an integer or string +// value may be any value + + + + + + "bar", 12 => true); + +echo $arr["foo"]; // bar +echo $arr[12]; // 1 +?> +]]> + + + + + A key may be either an + integer or a string. If a key is + the standard representation of an integer, it will + be interpreted as such (i.e. "8" will be + interpreted as 8, while + "08" will be interpreted as + "08"). + Floats in key are truncated to integer. + There are no different indexed and + associative array types in PHP; there is only one array type, + which can both contain integer and string indices. + + + A value can be of any PHP type. + + + array(6 => 5, 13 => 9, "a" => 42)); + +echo $arr["somearray"][6]; // 5 +echo $arr["somearray"][13]; // 9 +echo $arr["somearray"]["a"]; // 42 +?> +]]> + + + + + If you do not specify a key for a given value, then the maximum + of the integer indices is taken, and the new key will be that + maximum value + 1. If you specify a key that already has a value + assigned to it, that value will be overwritten. + + + 43, 32, 56, "b" => 12); + +// ...this array +array(5 => 43, 6 => 32, 7 => 56, "b" => 12); +?> +]]> + + + + + + As of PHP 4.3.0, the index generation behaviour described + above has changed. Now, if you append to an array in which + the current maximum key is negative, then the next key + created will be zero (0). Before, the new + index would have been set to the largest existing key + 1, + the same as positive indices are. + + + + Using &true; as a key will evaluate to integer + 1 as key. Using &false; as a key will evaluate + to integer 0 as key. Using + NULL as a key will evaluate to the empty + string. Using the empty string as key will create (or overwrite) + a key with the empty string and its value; it is not the same as + using empty brackets. + + + You cannot use arrays or objects as keys. Doing so will result in a + warning: Illegal offset type. + + + + + Creating/modifying with square-bracket syntax + + You can also modify an existing array by explicitly setting + values in it. + + + 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 may be an integer or string +// value may be any value + + If $arr doesn't exist yet, 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 an element specified with its key. If you want to + remove a key/value pair, you need to unset it. + + + 1, 12 => 2); + +$arr[] = 56; // This is the same as $arr[13] = 56; + // at this point of the script + +$arr["x"] = 42; // This adds a new element to + // the array with key "x" + +unset($arr[5]); // This removes the element from the array + +unset($arr); // This deletes the whole array +?> +]]> + + + + + + As mentioned above, if you provide the brackets with no key + specified, then the maximum of the existing integer indices is + taken, and the new key will be that maximum value + 1 . If no + integer indices exist yet, the key will be 0 + (zero). If you specify a key that already has a value assigned + to it, that value will be overwritten. + + + + + As of PHP 4.3.0, the index generation behaviour described + above has changed. Now, if you append to an array in which + the current maximum key is negative, then the next key + created will be zero (0). Before, the new + index would have been set to the largest existing key + 1, + the same as positive indices are. + + + + + Note that the maximum integer key used for this need + not currently exist in the array. It simply must + have existed in the array at some time since the last time the + array was re-indexed. The following example illustrates: + + + + + $value) { + unset($array[$i]); +} +print_r($array); + +// Append an item (note that the new key is 5, instead of 0 as you +// might expect). +$array[] = 6; +print_r($array); + +// Re-index: +$array = array_values($array); +$array[] = 7; +print_r($array); +?> +]]> + + &example.outputs; + + 1 + [1] => 2 + [2] => 3 + [3] => 4 + [4] => 5 +) +Array +( +) +Array +( + [5] => 6 +) +Array +( + [0] => 6 + [1] => 7 +) +]]> + + + + + + + + + Useful functions + + There are quite a few useful functions for working with arrays. + See the array functions section. + + + + The unset function allows unsetting keys of an + array. Be aware that the array will NOT be reindexed. If you only + use "usual integer indices" (starting from zero, increasing by one), + you can achieve the reindex effect by using array_values. + + + 'one', 2 => 'two', 3 => 'three'); +unset($a[2]); +/* will produce an array that would have been defined as + $a = array(1 => 'one', 3 => 'three'); + and NOT + $a = array(1 => 'one', 2 =>'three'); +*/ + +$b = array_values($a); +// Now $b is array(0 => 'one', 1 =>'three') +?> +]]> + + + + + + + The foreach + control structure exists specifically for arrays. It + provides an easy way to traverse an array. + + + + + Array do's and don'ts + + + Why is <literal>$foo[bar]</literal> wrong? + + You should always use quotes around a string literal + array index. For example, use $foo['bar'] and not + $foo[bar]. But why is $foo[bar] wrong? You might have seen the + following syntax in old scripts: + + + +]]> + + + This is wrong, but it works. Then, why is it wrong? The reason + is that this code has an undefined constant (bar) rather than a + string ('bar' - notice the quotes), and PHP may in future define + constants which, unfortunately for your code, have the same + name. It works because PHP automatically converts a + bare string (an unquoted string which does + not correspond to any known symbol) into a string which contains + the bare string. For instance, if there is no defined constant + named bar, then PHP will substitute in the + string 'bar' and use that. + + + + This does not mean to always quote the + key. You do not want to quote keys which are constants or variables, as this will + prevent PHP from interpreting them. + + + + +]]> + + + &example.outputs; + + + + + + More examples to demonstrate this fact: + + + 'apple', 'veggie' => 'carrot'); + +// Correct +print $arr['fruit']; // apple +print $arr['veggie']; // carrot + +// Incorrect. This works but also throws a PHP error of +// level E_NOTICE because of an undefined constant named fruit +// +// Notice: Use of undefined constant fruit - assumed 'fruit' in... +print $arr[fruit]; // apple + +// Let's define a constant to demonstrate what's going on. We +// will assign value 'veggie' to a constant named fruit. +define('fruit', 'veggie'); + +// Notice the difference now +print $arr['fruit']; // apple +print $arr[fruit]; // carrot + +// The following is okay as it's inside a string. Constants are not +// looked for within strings so no E_NOTICE error here +print "Hello $arr[fruit]"; // Hello apple + +// With one exception, braces surrounding arrays within strings +// allows constants to be looked for +print "Hello {$arr[fruit]}"; // Hello carrot +print "Hello {$arr['fruit']}"; // Hello apple + +// This will not work, results in a parse error such as: +// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING' +// This of course applies to using superglobals in strings as well +print "Hello $arr['fruit']"; +print "Hello $_GET['foo']"; + +// Concatenation is another option +print "Hello " . $arr['fruit']; // Hello apple +?> +]]> + + + + + When you turn error_reporting up to show + E_NOTICE level errors (such as setting + it to E_ALL) then you will see these + errors. By default, + error_reporting is turned down to not show them. + + + As stated in the syntax section, + there must be an expression between the square brackets + ('[' and ']'). That means + that you can write things like this: + + + +]]> + + + This is an example of using a function return value + as the array index. PHP also knows about constants, + as you may have seen the E_* ones + before. + + + + +]]> + + + Note that E_ERROR is also a valid identifier, + just like bar in the first example. But the last + example is in fact the same as writing: + + + +]]> + + + because E_ERROR equals 1, etc. + + + As we already explained in the above examples, + $foo[bar] still works but is wrong. + It works, because bar is due to its syntax + expected to be a constant expression. However, in this case no + constant with the name bar exists. PHP now + assumes that you meant bar literally, + as the string "bar", but that you forgot + to write the quotes. + + + So why is it bad then? + + At some point in the future, the PHP team might want to add another + constant or keyword, or you may introduce another constant into your + application, and then you get in trouble. For example, + you already cannot use the words empty and + default this way, since they are special + reserved keywords. + + + + To reiterate, inside a double-quoted string, it's + valid to not surround array indexes with quotes so + "$foo[bar]" is valid. See the above + examples for details on why as well as the section on + variable parsing + in strings. + + + + + + + + Converting to array + + + For any of the types: integer, float, + string, boolean and resource, + if you convert a value to an array, you get an array + with one element (with index 0), which is the scalar value you + started with. + + + + If you convert an object to an array, you get the + properties (member variables) of that object as the array's elements. + The keys are the member variable names with a few notable exceptions: + private variables have the class name prepended to the variable name; + protected variables have a '*' prepended to the variable name. + These prepended values have null bytes on either side. This can result + in some unexpected behaviour. + + + +]]> + + + + The above will appear to have two keys named 'AA', although one + of them is actually named '\0A\0A'. + + + + If you convert a &null; value to an array, you get an empty array. + + + + + Comparing + + It is possible to compare arrays by array_diff and + by Array operators. + + + + + Examples + + The array type in PHP is very versatile, so here will be some + examples to show you the full power of arrays. + + + + + '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['name'] = 'apple'; +$a[] = 4; // key will be 0 + +$b[] = 'a'; +$b[] = 'b'; +$b[] = 'c'; +// will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'), +// or simply array('a', 'b', 'c') +?> +]]> + + + + + + Using array() + + 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 + + +]]> + + &example.outputs; + + + + + + + Changing values of the array directly is possible since PHP 5 by passing + them as reference. Prior versions need workaround: + + Collection + + $color) { + $colors[$key] = strtoupper($color); +} + +print_r($colors); +?> +]]> + + &example.outputs; + + RED + [1] => BLUE + [2] => GREEN + [3] => YELLOW +) +]]> + + + + + This example creates a one-based array. + + One-based index + + 'January', 'February', 'March'); +print_r($firstquarter); +?> +]]> + + &example.outputs; + + 'January' + [2] => 'February' + [3] => 'March' +) +]]> + + + + + Filling an array + + +]]> + + + + Arrays are ordered. You can also change the order using various + sorting functions. See the array + functions section for more information. You can count + the number of items in an array using the + count function. + + + Sorting an array + + +]]> + + + + Because the value of an array can be anything, it can also be + another array. This way you can make recursive and + multi-dimensional arrays. + + + Recursive and multi-dimensional arrays + + array ( "a" => "orange", + "b" => "banana", + "c" => "apple" + ), + "numbers" => array ( 1, + 2, + 3, + 4, + 5, + 6 + ), + "holes" => array ( "first", + 5 => "second", + "third" + ) + ); + +// Some examples to address values in the array above +echo $fruits["holes"][5]; // prints "second" +echo $fruits["fruits"]["a"]; // prints "orange" +unset($fruits["holes"][0]); // remove "first" + +// Create a new multi-dimensional array +$juices["apple"]["green"] = "good"; +?> +]]> + + + + You should be aware that array assignment always involves + value copying. It also means that the internal array pointer used by + current and similar functions is reset. + You need to use the reference operator to copy + an array by reference. + + + +]]> + + + + + + + diff --git a/language/types/boolean.xml b/language/types/boolean.xml new file mode 100644 index 0000000000..fc9e251b85 --- /dev/null +++ b/language/types/boolean.xml @@ -0,0 +1,168 @@ + + + + Booleans + + + This is the easiest type. A boolean expresses a + truth value. It can be either &true; or &false;. + + + + + 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. + + + +]]> + + + + + Usually you + use some kind of operator + which returns a boolean value, and then pass it + on to a control + structure. + + +\n"; +} + +// ...because you can simply type +if ($show_separators) { + echo "
\n"; +} +?> +]]> + + + + + + + Converting to boolean + + To explicitly 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 automatically 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;: + + + + the boolean + &false; itself + + + the integer 0 (zero) + + + the float + 0.0 (zero) + + + the empty string, and the string + "0" + + + an array + with zero elements + + + an object + with zero member variables (PHP 4 only) + + + the special type NULL (including unset variables) + + + + SimpleXML + objects created from empty tags + + + + + Every other value is considered &true; (including any + resource). + + + -1 is considered + &true;, like any other non-zero (whether negative + or positive) number! + + + + + +]]> + + + + + + + diff --git a/language/types/float.xml b/language/types/float.xml new file mode 100644 index 0000000000..c958071fb5 --- /dev/null +++ b/language/types/float.xml @@ -0,0 +1,95 @@ + + + + Floating point numbers + + Floating point numbers (AKA "floats", "doubles" or "real numbers") can be + specified using any of the following syntaxes: + + + +]]> + + + Formally: + + + + + + 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). + + + + Floating point precision + + It is quite usual that simple decimal fractions like + 0.1 or 0.7 cannot be + converted into their internal binary counterparts without a + little loss of precision. This can lead to confusing results: for + example, floor((0.1+0.7)*10) will usually + return 7 instead of the expected + 8 as the result of the internal representation + really being something like 7.9999999999.... + + + 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, 1/3 in decimal form + becomes 0.3333333. . .. + + + 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 arbitrary precision math functions + or gmp functions instead. + + + + + Converting to float + + + For information on when and how strings are converted to floats, + see the section titled String + conversion to numbers. 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 Converting + to integer section for more information. + As of PHP 5, notice is thrown if you try to convert object to float. + + + + + diff --git a/language/types/integer.xml b/language/types/integer.xml new file mode 100644 index 0000000000..6c2f78d89b --- /dev/null +++ b/language/types/integer.xml @@ -0,0 +1,261 @@ + + + + Integers + + + An integer is a number of the set + Z = {..., -2, -1, 0, 1, 2, ...}. + + + + See also: + Arbitrary length integer / GMP, + Floating point numbers, and + Arbitrary precision / BCMath + + + + 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 + + +]]> + + + Formally the possible structure for integer literals is: + + + + + + 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 PHP_INT_SIZE, + maximum value from PHP_INT_MAX since PHP 4.4.0 and + PHP 5.0.5. + + + + If an invalid digit is passed to octal integer (i.e. 8 or 9), the rest + of the number is ignored. + + Octal weirdness + + +]]> + + + + + + + + Integer overflow + + If you specify a number beyond the bounds of the integer + type, it will be interpreted as a float instead. Also, if + you perform an operation that results in a number beyond the bounds of + the integer type, a float will be returned + instead. + + + + +]]> + + + + + 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 -50000 * + $million, the result will be + -429496728. However, when both operands are + positive there is no problem. + + + This is solved in PHP 4.1.0. + + + + + There is no integer division operator in PHP. + 1/2 yields the float + 0.5. You can cast the value to + an integer to always round it downwards, or you can + use the round function. + + + +]]> + + + + + + + + Converting to integer + + To explicitly 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 automatically converted if an operator, function or + control structure requires an integer argument. + You can also convert a value to integer with the function + intval. + + + See also type-juggling. + + + + From <link linkend="language.types.boolean" + >booleans</link> + + &false; will yield + 0 (zero), and &true; + will yield 1 (one). + + + + + From <link linkend="language.types.float">floating point numbers</link> + + When converting from float to integer, the number will + be rounded towards zero. + + + + If the float is beyond the boundaries of integer + (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! + + + + Never cast an unknown fraction to integer, as this can + sometimes lead to unexpected results. + + + +]]> + + + + See for more information the warning + about float-precision. + + + + + From strings + + See String + conversion to 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 rely on this behaviour, as it can + change without notice. + + + + + + + + diff --git a/language/types/null.xml b/language/types/null.xml new file mode 100644 index 0000000000..64f98dc65f --- /dev/null +++ b/language/types/null.xml @@ -0,0 +1,77 @@ + + + + NULL + + + The special &null; value represents + that a variable has no value. &null; is the only possible value of type + NULL. + + + + The null type was introduced in PHP 4. + + + + A variable is considered to be &null; if + + + + it has been assigned the constant &null;. + + + + + it has not been set to any value yet. + + + + + it has been unset. + + + + + + + Syntax + + There is only one value of type &null;, and that is + the case-insensitive keyword &null;. + + + +]]> + + + + + See also is_null and unset. + + + + + diff --git a/language/types/object.xml b/language/types/object.xml new file mode 100644 index 0000000000..bb1256388b --- /dev/null +++ b/language/types/object.xml @@ -0,0 +1,83 @@ + + + + Objects + + + Object Initialization + + + To initialize an object, you use the new + statement to instantiate the object to a variable. + + + +do_foo(); +?> +]]> + + + + + For a full discussion, please read the section Classes and Objects. + + + + + Converting to object + + + 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 + stdClass 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 scalar will + contain the value. + + +scalar; // outputs 'ciao' +?> +]]> + + + + + + + + diff --git a/language/types/psuedo-types.xml b/language/types/psuedo-types.xml new file mode 100644 index 0000000000..9ffa9f09cc --- /dev/null +++ b/language/types/psuedo-types.xml @@ -0,0 +1,167 @@ + + + + Pseudo-types and variables used in this documentation + + + mixed + + mixed indicates that a parameter may accept multiple (but not + necessarily all) types. + + + gettype for example will accept all PHP types, + while str_replace will accept strings and arrays. + + + + + number + + number indicates that a parameter can be either + integer or float. + + + + + callback + + Some functions like call_user_func + or usort accept user defined + callback functions as a parameter. Callback functions can not only + be simple functions but also object methods including static class + methods. + + + 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 + array, + echo, + empty, + eval, + exit, + isset, + list, + print or + unset cannot be called using a callback. + + + 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. + + + 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. + + + Apart from common user-defined function, + create_function can be used to create an anonymous + callback function. + + + + + + Callback function examples + + + +]]> + + + + + + 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 References Explained. + + + + + + + void + + void in return type means that the return value is + useless. void in parameters list means that the + function doesn't accept any parameters. + + + + + ... + + $... in function prototypes means + and so on. + This variable name is used when a function can take an endless number of + arguments. + + + + + diff --git a/language/types/resource.xml b/language/types/resource.xml new file mode 100644 index 0000000000..3a00896315 --- /dev/null +++ b/language/types/resource.xml @@ -0,0 +1,81 @@ + + + + Resource + + + A resource is a special variable, holding + a reference to an external resource. Resources + are created and used by special functions. + See the appendix + for a listing of all these + functions and the corresponding resource types. + + + + + The resource type was introduced in PHP 4 + + + + + See also get_resource_type. + + + + Converting to resource + + + 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. + + + + + Freeing resources + + + 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. + + + Persistent database links are special, they + are not destroyed by the + garbage collector. See also the section about persistent + connections. + + + + + + + + diff --git a/language/types/string.xml b/language/types/string.xml new file mode 100644 index 0000000000..6d90ad06e5 --- /dev/null +++ b/language/types/string.xml @@ -0,0 +1,729 @@ + + + + Strings + + A string 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. See utf8_encode + and utf8_decode for some Unicode support. + + + + It is no problem for a string to become very large. + There is no practical bound to the size + of strings imposed by PHP, so there is no reason at all + to worry about long strings. + + + + Syntax + + A string literal can be specified in three different + ways. + + + + + single quoted + + + + + double quoted + + + + + heredoc syntax + + + + + + + Single quoted + + The easiest way to specify a simple string is to + enclose it in single quotes (the character '). + + + To specify a literal single + quote, you will need to escape it with a backslash + (\), 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 will also be printed! So + usually there is no need to escape the backslash itself. + + + In PHP 3, a warning will + be issued at the E_NOTICE level when this + happens. + + + + + Unlike the two other syntaxes, variables and escape sequences + for special characters will not be expanded + when they occur in single quoted strings. + + + + + +]]> + + + + + + Double quoted + + If the string is enclosed in double-quotes ("), + PHP understands more escape sequences for special + characters: + + + Escaped characters + + + + sequence + meaning + + + + + \n + linefeed (LF or 0x0A (10) in ASCII) + + + \r + carriage return (CR or 0x0D (13) in ASCII) + + + \t + horizontal tab (HT or 0x09 (9) in ASCII) + + + \v + vertical tab (VT or 0x0B (11) in ASCII) (since PHP 5.2.5) + + + \f + form feed (FF or 0x0C (12) in ASCII) (since PHP 5.2.5) + + + \\ + backslash + + + \$ + dollar sign + + + \" + double-quote + + + \[0-7]{1,3} + + the sequence of characters matching the regular + expression is a character in octal notation + + + + \x[0-9A-Fa-f]{1,2} + + the sequence of characters matching the regular + expression is a character in hexadecimal notation + + + + +
+ + Again, if you try to escape any other character, the + backslash will be printed too! + Before PHP 5.1.1, backslash in \{$var} hasn't been + printed. + + + But the most important feature of double-quoted strings + is the fact that variable names will be expanded. + See string + parsing for details. + + + + + Heredoc + + Another way to delimit strings is by using heredoc syntax + ("<<<"). One should provide an identifier (followed by new line) after + <<<, then the string, and then the + same identifier to close the quotation. + + + The closing identifier must begin in the + 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. + + + + + It is very important to note that the line with the closing + identifier contains no other characters, except + possibly a semicolon (;). + That means especially that the identifier + may not be indented, and there + may not be any spaces or tabs after or before the semicolon. + It's also important to realize that the first character before + the closing identifier must be a newline as defined by your + operating system. This is \r on Macintosh + for example. Closing delimiter (possibly followed by a semicolon) must + be followed by a newline too. + + + If this rule is broken and the closing identifier is not "clean" + then it's not considered to be a closing identifier and PHP + will continue looking for one. If in this case a proper closing + identifier is not found then a parse error will result with the + line number being at the end of the script. + + + It is not allowed to use heredoc syntax in initializing class members. + Use other string syntaxes instead. + + Invalid example + + +]]> + + + + + + + Heredoc text behaves just like a double-quoted string, without + the double-quotes. This means that you do not need to escape quotes + in your here docs, but you can still use the escape codes listed + above. Variables are expanded, but the same care must be taken + when expressing complex variables inside a heredoc as with + strings. + + Heredoc string quoting example + +foo = 'Foo'; + $this->bar = array('Bar1', 'Bar2', 'Bar3'); + } +} + +$foo = new foo(); +$name = 'MyName'; + +echo <<foo. +Now, I am printing some {$foo->bar[1]}. +This should print a capital 'A': \x41 +EOT; +?> +]]> + + + + + + + Heredoc support was added in PHP 4. + + + + + + Variable parsing + + When a string is specified in double quotes or with + heredoc, variables are + parsed within it. + + + There are two types of syntax: a + simple + one and a + complex + one. + The simple syntax is the most common and convenient. It provides a way + to parse a variable, an array value, or an + object property. + + + The complex syntax was introduced in PHP 4, and can be recognised + by the curly braces surrounding the expression. + + + + Simple syntax + + If a dollar sign ($) is encountered, the + parser will greedily take as many tokens as possible to form a + valid variable name. Enclose the variable name in curly + braces if you want to explicitly specify the end of the name. + + + + +]]> + + + + Similarly, you can also have an array index or an + object property parsed. With array indices, the closing square + bracket (]) marks the end of the index. For + object properties the same rules apply as to simple variables, + though with object properties there doesn't exist a trick like + the one with variables. + + + + + + + 'red', 'banana' => 'yellow'); + +// Works but note that this works differently outside string-quotes +echo "A banana is $fruits[banana]."; + +// Works +echo "A banana is {$fruits['banana']}."; + +// Works but PHP looks for a constant named banana first +// as described below. +echo "A banana is {$fruits[banana]}."; + +// Won't work, use braces. This results in a parse error. +echo "A banana is $fruits['banana']."; + +// Works +echo "A banana is " . $fruits['banana'] . "."; + +// Works +echo "This square is $square->width meters broad."; + +// Won't work. For a solution, see the complex syntax. +echo "This square is $square->width00 centimeters broad."; +?> +]]> + + + + + For anything more complex, you should use the complex syntax. + + + + + Complex (curly) syntax + + This isn't called complex because the syntax is complex, + but because you can include complex expressions this way. + + + In fact, you can include any value that is in the namespace + in strings with this syntax. You simply write the expression + 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 "{$"). + Some examples to make it clear: + + + +width}00 centimeters broad."; + +// Works +echo "This works: {$arr[4][3]}"; + +// This is wrong for the same reason as $foo[bar] is wrong +// outside a string. In other words, it will still work but +// because PHP first looks for a constant named foo, it will +// throw an error of level E_NOTICE (undefined constant). +echo "This is wrong: {$arr[foo][3]}"; + +// Works. When using multi-dimensional arrays, always use +// braces around arrays when inside of strings +echo "This works: {$arr['foo'][3]}"; + +// Works. +echo "This works: " . $arr['foo'][3]; + +echo "You can even write {$obj->values[3]->name}"; + +echo "This is the value of the var named $name: {${$name}}"; + +echo "This is the value of the var named by the return value of getName(): {${getName()}}"; + +echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}"; +?> +]]> + + + + + + + Functions and method calls inside {$ } work since PHP 5. + + + + + Parsing variables within strings uses more memory than string + concatenation. When writing a PHP script in which memory usage is a + concern, consider using the concatenation operator (.) rather than + variable parsing. + + + + + + + String access and modification by character + + Characters within strings may be accessed and modified by specifying the + zero-based offset of the desired character after the string + using square array-brackets like $str[42] so think of + a string as an array of characters. + + + + They may also be accessed using braces like $str{42} + for the same purpose. However, using square array-brackets is preferred + because the {braces} style is deprecated as of PHP 6. + + + + + Some string examples + + +]]> + + + + + + Accessing by [] or {} to + variables of other type silently returns &null;. + + + + + + + + Useful functions and operators + + Strings may be concatenated using the '.' (dot) operator. Note + that the '+' (addition) operator will not work for this. Please + see String + operators for more information. + + + There are a lot of useful functions for string modification. + + + See the string functions section + for general functions, the regular expression functions for + advanced find&replacing (in two tastes: + Perl and + POSIX extended). + + + There are also functions for URL-strings, + and functions to encrypt/decrypt strings + (mcrypt and + mhash). + + + Finally, if you still didn't find what you're looking for, + see also the character type functions. + + + + + Converting to string + + + You can convert a value to a string using the (string) + cast, or the strval function. String conversion + is automatically done in the scope of an expression for you where a + string is needed. This happens when you use the echo + or print functions, or when you compare a variable + value to a string. Reading the manual sections on Types and Type Juggling will make + the following clearer. See also settype. + + + + A boolean &true; value is converted to the string "1", + the &false; value is represented as "" (empty string). + This way you can convert back and forth between boolean and string values. + + + An integer or a floating point number (float) + is converted to a string representing the number with its digits + (including the exponent part for floating point numbers). + Floating point numbers can be converted using the exponential notation + (4.1E+6). + + + + The decimal point character is defined in the script's + locale (category LC_NUMERIC). + See setlocale. + + + + Arrays are always converted to the string "Array", + so you cannot dump out the contents of an array with + echo or print to see what is inside + them. To view one element, you'd do something like + echo $arr['foo']. See below for tips on dumping/viewing the + entire contents. + + + Objects in PHP 4 are always converted to the string "Object". + If you would like to print out the member variable values of an + object for debugging reasons, read the paragraphs + below. If you would like to find out the class name of which an object + is an instance of, use get_class. + As of PHP 5, __toString() method is used if applicable. + + + Resources are always converted to strings with the structure + "Resource id #1" where 1 is + the unique number of the resource assigned by PHP during runtime. + If you would like to get the type of the resource, use + get_resource_type. + + + &null; is always converted to an empty string. + + + + As you can see above, printing out the arrays, objects or resources does not + provide you any useful information about the values themselves. Look at the + functions print_r and var_dump + for better ways to print out values for debugging. + + + + You can also convert PHP values to strings to store them permanently. This + method is called serialization, and can be done with the function + serialize. You can also serialize PHP values to + XML structures, if you have WDDX support + in your PHP setup. + + + + + String conversion to numbers + + + When a string is evaluated as a numeric value, the resulting + value and type are determined as follows. + + + The string will evaluate as a float if it contains any of the + characters '.', 'e', or 'E'. Otherwise, it will evaluate as an + integer. + + + The value is given by the initial portion of the string. If the + string starts with valid numeric data, this will be the value + used. Otherwise, the value will be 0 (zero). Valid numeric data + is an optional sign, followed by one or more digits (optionally + containing a decimal point), followed by an optional + exponent. The exponent is an 'e' or 'E' followed by one or more + digits. + + + + +]]> + + + + For more information on this conversion, see the Unix manual page + for strtod(3). + + + 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: + + +\n"; +?> +]]> + + + + + Do not expect to get the code of one character by converting it + to integer (as you would do in C for example). Use the functions + ord and chr to convert + between charcodes and characters. + + + + + + diff --git a/language/types/type-juggling.xml b/language/types/type-juggling.xml new file mode 100644 index 0000000000..f388253dbe --- /dev/null +++ b/language/types/type-juggling.xml @@ -0,0 +1,261 @@ + + + + Type Juggling + + + 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 $var, + $var becomes a string. If you then assign an + integer value to $var, it becomes an + integer. + + + 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. + + + +]]> + + + + + + If the last two examples above seem odd, see String + conversion to numbers. + + + If you wish to force a variable to be evaluated as a certain type, + see the section on Type + casting. If you wish to change the type of a variable, see + settype. + + + If you would like to test any of the examples in this section, you + can use the var_dump function. + + + + The behaviour of an automatic conversion to array is currently + undefined. + + + 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: + + + +]]> + + + + + See the section titled String + access by character for more information. + + + + + Type Casting + + + 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. + + + +]]> + + + + + The casts allowed are: + + + (int), (integer) - cast to integer + + + (bool), (boolean) - cast to boolean + + + (float), (double), (real) - cast to float + + + (string) - cast to string + + + (binary) - cast to binary string (PHP 6) + + + (array) - cast to array + + + (object) - cast to object + + + + + (binary) casting and b prefix forward support was added in PHP 5.2.1 + + + Note that tabs and spaces are allowed inside the parentheses, so + the following are functionally equivalent: + + + +]]> + + + Casting a literal strings and variables to binary strings: + + + +]]> + + + + + + Instead of casting a variable to string, you can also enclose + the variable in double quotes. + + + +]]> + + + + + + + It may not be obvious exactly what will happen when casting + between certain types. For more info, see these sections: + + + + Converting to + boolean + + + Converting to + integer + + + Converting to + float + + + Converting to + string + + + Converting to + array + + + Converting to + object + + + Converting to + resource + + + + + The type comparison tables + + + + + + + +