From c272030e25fbfb19ad35f1a62cf148374fa1d7ee Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Thu, 1 Mar 2012 16:51:53 +0000 Subject: [PATCH] Restructure array docs so related information goes together (like key type handling). Also add note about 5.4 syntax. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@323718 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/types/array.xml | 337 +++++++++++++++++++++++++++++---------- 1 file changed, 253 insertions(+), 84 deletions(-) diff --git a/language/types/array.xml b/language/types/array.xml index b503b5294e..2e25d9fb7e 100644 --- a/language/types/array.xml +++ b/language/types/array.xml @@ -26,49 +26,276 @@ Specifying with <function>array</function> - An array can be created by the array - language construct. It takes as parameters any number of comma-separated - key => - value pairs. + An array can be created using the array + language construct. It takes any number of comma-separated + key => value pairs + as arguments. -array( key => value - , ... - ) -// key may only be an integer or string -// value may be any value of any type +array( + key => value, + key2 => value2, + key3 => value3, + ... +) - + + As of PHP 5.4 you can also use the short array syntax, which replaces + array() with []. + + + + A simple array "bar", 12 => true); +$array = array( + "foo" => "bar", + "bar" => "foo" +); -echo $arr["foo"]; // bar -echo $arr[12]; // 1 +// as of PHP 5.4 +$array = [ + "foo" => "bar", + "bar" => "foo" +]; ?> ]]> - - + + - 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. The indexed and associative array types - are the same type in PHP, which can both contain integer and - string indices. + The key can either be an integer + or a string. The value can be + of any type. - + - A value can be any PHP type. + Additionally the following key casts will occur: + + + + Strings containing valid integers will be cast to the + integer type. E.g. the key "8" will actually be + stored under 8. On the other hand "08" will + not be cast, as it isn't a valid decimal integer. + + + + + Floats are also cast to integers, which means that the + fractional part will be truncated. E.g. the key 8.7 will actually + be stored under 8. + + + + + Bools are cast to integers, too, i.e. the key + true will actually be stored under 1 + and the key false under 0. + + + + + Null will be cast to the empty string, i.e. the key + null will actually be stored under "". + + + + + Arrays and objects can not be used as keys. + Doing so will result in a warning: Illegal offset type. + + + + + + If multiple elements in the array declaration use the same key, only the last one + will be used as all others are overwritten. + + + + Type Casting and Overwriting example + + "a", + "1" => "b", + 1.5 => "c", + true => "d", +); +var_dump($array); +?> +]]> + + &example.outputs; + + + string(1) "d" +} +]]> + + + As all the keys in the above example are cast to 1, the value will be overwritten + on every new element and the last assined value "d" is the only one left over. + + + + + PHP arrays can contain integer and string keys at the same time + as PHP does not distinguish between indexed and associative arrays. + + + + Mixed <type>integer</type> and <type>string</type> keys + + "bar", + "bar" => "foo", + 100 => -100, + -100 => 100, +); +var_dump($array); +?> +]]> + + &example.outputs; + + + string(3) "bar" + ["bar"]=> + string(3) "foo" + [100]=> + int(-100) + [-100]=> + int(100) +} +]]> + + + + + The key is optional. If it is not specified, PHP will + use the increment of the largest previously used integer key. + + + + Indexed arrays without key + + +]]> + + &example.outputs; + + + string(3) "foo" + [1]=> + string(3) "bar" + [2]=> + string(5) "hallo" + [3]=> + string(5) "world" +} +]]> + + + + + It is possible to specify the key only for some elements and leave it out for others: + + + + Keys not on all elements + + "c", + "d", +); +var_dump($array); +?> +]]> + + &example.outputs; + + + string(1) "a" + [1]=> + string(1) "b" + [6]=> + string(1) "c" + [7]=> + string(1) "d" +} +]]> + + + As you can see the last value "d" was assigned the key + 7. This is because the largest integer key before that + was 6. + + + + + + Accessing array elements with square bracket syntax + + + Array elements can be accessed using the array[key] syntax. + + + + Accessing array elements + + "bar", + 42 => 24, + "multi" => array( + "dimensional" => array( + "array" => "foo" + ) + ) +); +var_dump($array["foo"]); +var_dump($array[42]); +var_dump($array["multi"]["dimensional"]["array"]); +?> +]]> + + &example.outputs; + + + + + Attempting to access an array key which has not been defined is @@ -77,64 +304,6 @@ echo $arr[12]; // 1 issued, and the result will be &null;. - - - - array(6 => 5, 13 => 9, "a" => 42)); - -echo $arr["somearray"][6]; // 5 -echo $arr["somearray"][13]; // 9 -echo $arr["somearray"]["a"]; // 42 -?> -]]> - - - - - If a key is not specified for a value, the maximum of the - integer indices is taken and the new key will be that value - plus 1. If a key that already has an assigned value is specified, that value - will be overwritten. - - - - - 43, 32, 56, "b" => 12); - -// ...this array -array(5 => 43, 6 => 32, 7 => 56, "b" => 12); -?> -]]> - - - - - - Before PHP 4.3.0, appending to an array in which the current - maximum key was negative would create a new key as described above. Since - PHP 4.3.0, the new key will be 0. - - - - - Using &true; as key will evaluate to integer - 1 as a key. Using &false; as key will - evaluate to integer 0 as a key. Using - &null; as a key will evaluate to the empty string. Using the empty string as - a key will create (or overwrite) a key with the empty string and its value; - it is not the same as using empty brackets. - - - - Arrays and objects can not be used as keys. Doing - so will result in a warning: Illegal offset type. - -