goba Mon Nov 4 12:34:52 2002 EDT Modified files: /phpdoc/en/language types.xml Log: Going on with general cleanups. Removing the whole outdated and long ago commented single/multidimensional array parts. Adding more examples, adding some points that were in TODO.
Index: phpdoc/en/language/types.xml diff -u phpdoc/en/language/types.xml:1.94 phpdoc/en/language/types.xml:1.95 --- phpdoc/en/language/types.xml:1.94 Mon Nov 4 10:45:11 2002 +++ phpdoc/en/language/types.xml Mon Nov 4 12:34:52 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.94 $ --> +<!-- $Revision: 1.95 $ --> <chapter id="language.types"> <title>Types</title> @@ -907,7 +907,7 @@ echo "This is { $great}"; // won't work, outputs: This is { fantastic} echo "This is {$great}"; // works, outputs: This is fantastic echo "This square is {$square->width}00 centimeters broad."; -echo "This works: {$arr[4][3]}"; +echo "This works: {$arr[4][3]}"; // This is wrong for the same reason // as $foo[bar] is wrong outside a string. @@ -946,35 +946,15 @@ <example> <title>Some string examples</title> <programlisting role="php"> -<!-- TODO: either move these examples to a example section, -as with arrays, or distribute them under the applicable -sections. --> <![CDATA[ <?php -/* Assigning a string. */ -$str = "This is a string"; - -/* Appending to it. */ -$str = $str . " with some more text"; - -/* Another way to append, includes an escaped newline. */ -$str .= " and a newline at the end.\n"; - -/* This string will end up being '<p>Number: 9</p>' */ -$num = 9; -$str = "<p>Number: $num</p>"; - -/* This one will be '<p>Number: $num</p>' */ -$num = 9; -$str = '<p>Number: $num</p>'; - -/* Get the first character of a string */ +// Get the first character of a string $str = 'This is a test.'; $first = $str{0}; -/* Get the last character of a string. */ +// Get the last character of a string. $str = 'This is still a test.'; -$last = $str{strlen($str)-1}; +$last = $str{strlen($str)-1}; ?> ]]> </programlisting> @@ -985,7 +965,7 @@ </sect2><!-- end syntax --> <sect2 id="language.types.string.useful-funcs"> - <title>Useful functions</title><!-- and operators --> + <title>Useful functions and operators</title> <para> Strings may be concatenated using the '.' (dot) operator. Note that the '+' (addition) operator will not work for this. Please @@ -1013,6 +993,7 @@ see also the <link linkend="ref.ctype">character type functions</link>. </simpara> </sect2> + <sect2 id="language.types.string.casting"> <title>Converting to string</title> @@ -1145,8 +1126,7 @@ 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, <!-- is a map --> - collection, + dictionary, collection, stack, queue and probably more. Because you can have another PHP-array as a value, you can also quite easily simulate trees. @@ -1154,10 +1134,8 @@ <para> Explanation 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, we refer you to - external literature about this broad topic. - <!-- like goodrich&tamassia: datastructures and algorithmes. - Only, the subtitle is: in Java, and it's quite academic too --> + For more information we refer you to external literature about + this broad topic. </para> <sect2 id="language.types.array.syntax"> @@ -1170,19 +1148,47 @@ language-construct. It takes a certain number of comma-separated <literal><replaceable>key</replaceable> => <replaceable >value</replaceable></literal> - pairs. + pairs. + </para> + <para> + <synopsis> +array( <optional> <replaceable>key</replaceable> => </optional> <replaceable +>value</replaceable> + , ... + ) +// <replaceable>key</replaceable> is either <type>string</type + > or nonnegative <type>integer</type> +// <replaceable>value</replaceable> can be anything + </synopsis> + </para> + <para> + <informalexample> + <programlisting role="php"> +<![CDATA[ +array("foo" => "bar", 12 => true); +]]> + </programlisting> + </informalexample> </para> <para> A <varname>key</varname> is either an <type>integer</type> - or a <type>string</type>. - If a key is the standard representation of an - <type>integer</type>, it will - be interpreted as such (i.e. <literal>"8"</literal> will be interpreted - as <literal>8</literal>, while - <literal>"08"</literal> will be interpreted as <literal>"08"</literal>). + or a <type>string</type>. If a key is the standard representation + of an <type>integer</type>, it will be interpreted as such (i.e. + <literal>"8"</literal> will be interpreted as <literal>8</literal>, + while <literal>"08"</literal> will be interpreted as + <literal>"08"</literal>). 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. </para> <para> - A value can be anything. + A value can be of any PHP type. + <informalexample> + <programlisting role="php"> +<![CDATA[ +array("somearray" => array(6 => 5, 13 => 9, "a" => 43)); +]]> + </programlisting> + </informalexample> </para> <para> If you omit a key, the maximum of the integer-indices is taken, and @@ -1192,12 +1198,23 @@ the new key. If no integer-indices exist yet, the key will be <literal>0</literal> (zero). If you specify a key that already has a value assigned to it, that value will be overwritten. + <informalexample> + <programlisting role="php"> +<![CDATA[ +// This array is the same as ... +array(5 => 43, 32, 56, "b" => 12); + +// ...this array +array(5 => 43, 6 => 32, 7 => 56, "b" => 12); +]]> + </programlisting> + </informalexample> </para> <para> - Using <literal>true</literal> as a key will evalute to + Using &true; as a key will evalute to <type>integer</type> <literal>1</literal> as key. Using - <literal>false</literal> as a key will evalute to <type>integer</type> - <literal>0</literal> as key. Using <literal>NULL</literal> as a key + &false; as a key will evalute to <type>integer</type> + <literal>0</literal> as key. Using <literal>NULL</literal> as a key will evaluate to an empty string. Using an emptry string as key will create (or overwrite) a key with an empty string and its value, it is not the same as using empty brackets. @@ -1206,31 +1223,17 @@ You cannot use arrays or objects as keys. Doing so will result in a warning: <literal>Illegal offset type</literal>. </para> - - <para> - <synopsis> -array( <optional> <replaceable>key</replaceable> => </optional> <replaceable ->value</replaceable> - , ... - ) -// <replaceable>key</replaceable> is either <type>string</type - > or nonnegative <type>integer</type> -// <replaceable>value</replaceable> can be anything - </synopsis> - </para> </sect3> <sect3 id="language.types.array.syntax.modifying"> <title>Creating/modifying with square-bracket syntax</title> <para> You can also modify an existing array, by explicitly setting - values. + values in it. </para> <para> 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 + key in brackets. You can also omit the key, add an empty pair of brackets ("<literal>[]</literal>") to the variable-name in that case. <synopsis> $arr[<replaceable>key</replaceable>] = <replaceable>value</replaceable>; @@ -1240,41 +1243,57 @@ // <replaceable>value</replaceable> can be anything </synopsis> If <varname>$arr</varname> doesn't exist yet, it will be created. - So this is also - an alternative way to specify an array. + 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 - <function>unset</function> it. - - </para> + to an element specified with its key. If you want to + remove a key/value pair, you need to <function>unset</function> it. + <informalexample> + <programlisting role="php"> +<![CDATA[ +$arr = array(5 => 1, 12 => 2); - </sect3> - +$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 +]]> + </programlisting> + </informalexample> + </para> + </sect3> </sect2><!-- end syntax --> <sect2 id="language.types.array.useful-funcs"> <title>Useful functions</title> <para> There are quite some useful function for working - with arrays, see the <link linkend="ref.array">array-functions</link> - section. + with arrays, see the <link linkend="ref.array">array + functions</link> section. </para> <note> <para> The <function>unset</function> function allows unsetting keys of an - array. Be aware that the array will NOT be reindexed. + 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 achive the reindex effect by using <function>array_values</function>. <informalexample> <programlisting role="php"> <![CDATA[ -$a = array( 1 => 'one', 2 => 'two', 3 => 'three' ); -unset( $a[2] ); +$a = array(1 => 'one', 2 => 'two', 3 => 'three'); +unset($a[2]); /* will produce an array that would have been defined as - $a = array( 1=>'one', 3=>'three'); + $a = array(1 => 'one', 3 => 'three'); and NOT - $a = array( 1 => 'one', 2 => 'three'); -*/ + $a = array(1 => 'one', 2 =>'three'); +*/ + +$b = array_values($a); +// Now b is array(1 => 'one', 2 =>'three') ]]> </programlisting> </informalexample> @@ -1286,8 +1305,6 @@ control structure exists specifically for arrays. It provides an easy way to traverse an array. </para> - - </sect2> <sect2 id="language.types.array.donts"> @@ -1312,7 +1329,8 @@ 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 the - undefined constant gets converted to a string of the same name. + undefined constant gets converted to a string of the same name + automatically for backward compatibility reasons. </para> <para> As stated in the <link linkend="language.types.array.syntax" @@ -1322,21 +1340,21 @@ <informalexample> <programlisting role="php"> <![CDATA[ -echo $arr[ foo(true) ]; +echo $arr[foo(true)]; ]]> </programlisting> </informalexample> This is an example of using a function return value - as the array index. PHP knows also about constants, - and you may have seen the - <literal>E_*</literal> before. + as the array index. PHP also knows about constants, + as you may have seen the <literal>E_*</literal> ones + before. <informalexample> <programlisting role="php"> <![CDATA[ -$error_descriptions[E_ERROR] = "A fatal error has occured"; +$error_descriptions[E_ERROR] = "A fatal error has occured"; $error_descriptions[E_WARNING] = "PHP issued a warning"; -$error_descriptions[E_NOTICE] = "This is just an informal notice"; +$error_descriptions[E_NOTICE] = "This is just an informal notice"; ]]> </programlisting> </informalexample> @@ -1367,7 +1385,8 @@ <title>So why is it bad then?</title> <para> At some point in the future, the PHP team might want to add another - constant or keyword, and then you get in trouble. For example, + 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 <literal>empty</literal> and <literal>default</literal> this way, since they are special <link linkend="reserved">reserved keywords</link>. @@ -1377,14 +1396,41 @@ When you turn <link linkend="function.error-reporting" >error_reporting</link> to <literal>E_ALL</literal>, you will see that PHP generates notices whenever an - <literal>index</literal> is used which is not defined - (put the line <literal>error_reporting(E_ALL);</literal> - in your script). + <literal>index</literal> is used which is not defined. + Consider this script: + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php + +// Turn on the display of all errors +error_reporting(E_ALL); + +// Define the test array +$abc = array("x" => "y"); + +// Access element with the *bad* method +echo $abc[x]; + +?> +]]> + </programlisting> + </informalexample> + The output is: + <informalexample> + <programlisting> +<![CDATA[ +<br /> +<b>Notice</b>: Use of undefined constant x - assumed 'x' in +<b>/path/to/script.php</b> on +line <b>10</b><br /> +]]> + </programlisting> + </informalexample> </simpara> </note> <note> <simpara> - Inside a double-quoted <type>string</type>, an other syntax + Inside a double-quoted <type>string</type>, another syntax is valid. See <link linkend="language.types.string.parsing" >variable parsing in strings</link> for more details. </simpara> @@ -1393,6 +1439,26 @@ </sect3> </sect2> + <sect2 id="language.types.array.casting"> + <title>Converting to array</title> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + If you convert a &null; value to an array, you get an empty array. + </para> + </sect2> + <sect2 id="language.types.array.examples"> <title>Examples</title> <para> @@ -1404,24 +1470,24 @@ <programlisting role="php"> <![CDATA[ // this -$a = array( 'color' => 'red' - , 'taste' => 'sweet' - , 'shape' => 'round' - , 'name' => 'apple' - , 4 // key will be 0 +$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['name'] = 'apple'; +$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' ), +// will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'), // or simply array('a', 'b', 'c') ]]> </programlisting> @@ -1433,40 +1499,38 @@ <programlisting role="php"> <![CDATA[ // Array as (property-)map -$map = array( 'version' => 4 - , 'OS' => 'Linux' - , 'lang' => 'english' - , 'short_tags' => true +$map = array( 'version' => 4, + 'OS' => 'Linux', + 'lang' => 'english', + 'short_tags' => true ); // strictly numerical keys -$array = array( 7 - , 8 - , 0 - , 156 - , -10 +$array = array( 7, + 8, + 0, + 156, + -10 ); -// this is the same as array( 0 => 7, 1 => 8, ...) +// 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 +$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(); ]]> <!-- TODO example of -- mixed keys - overwriting keys -- integer keys as string - using vars/functions as key/values -- mixed skipping +- warning about references --> </programlisting> </example> @@ -1475,9 +1539,9 @@ <title>Collection</title> <programlisting role="php"> <![CDATA[ -$colors = array('red','blue','green','yellow'); +$colors = array('red', 'blue', 'green', 'yellow'); -foreach ( $colors as $color ) { +foreach ($colors as $color) { echo "Do you like $color?\n"; } @@ -1509,7 +1573,7 @@ // won't work: //$color = strtoupper($color); - //works: + // works: $colors[$key] = strtoupper($color); } print_r($colors); @@ -1549,13 +1613,12 @@ </example> </para> <example> - <title>Filling real array</title> + <title>Filling an array</title> <programlisting role="php"> <![CDATA[ // fill an array with all items from a directory $handle = opendir('.'); -while ($file = readdir($handle)) -{ +while ($file = readdir($handle)) { $files[] = $file; } closedir($handle); @@ -1564,8 +1627,10 @@ </example> <para> Arrays are ordered. You can also change the order using various - sorting-functions. See <link linkend="ref.array">array-functions</link> - for more information. + sorting-functions. See the <link linkend="ref.array">array + functions</link> section for more information. You can count + the number of items in an array using the + <function>count</function> function. </para> <example> <title>Sorting array</title> @@ -1585,228 +1650,50 @@ <title>Recursive and multi-dimensional arrays</title> <programlisting role="php"> <![CDATA[ -$fruits = array ( "fruits" => array ( "a" => "orange" - , "b" => "banana" - , "c" => "apple" - ) - , "numbers" => array ( 1 - , 2 - , 3 - , 4 - , 5 - , 6 - ) - , "holes" => array ( "first" - , 5 => "second" - , "third" +$fruits = array ( "fruits" => 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"; ]]> -<!-- quite duplicate... -$a = array( - "apple" => array( - "color" => "red", - "taste" => "sweet", - "shape" => "round" - ), - "orange" => array( - "color" => "orange", - "taste" => "tart", - "shape" => "round" - ), - "banana" => array( - "color" => "yellow", - "taste" => "paste-y", - "shape" => "banana-shaped" - ) -); ---> </programlisting> </example> - - </sect2> - - <!-- TODO - <sect2> - <title>Misc</title> - - </sect2> - - - example multi-dim with $arr[bla][bla] syntax - - converting to array - - warning about references - - note that assigning is copy (usually...) - - - --> - -<!-- there is no such thing as multi/singel dim arrays (at least in PHP4) - <sect2 id="language.types.array.single-dim"> - <title>Single Dimension Arrays</title> - <para> - PHP supports both scalar and associative arrays. In fact, there - is no difference between the two. You can create an array using - the - - <function>list</function> - - Nope - - - - - or <function>array</function> - functions, or you can explicitly set each array element value. - <informalexample> - <programlisting role="php"> -$a[0] = "abc"; -$a[1] = "def"; -$b["foo"] = 13; - </programlisting> - </informalexample> - </para> - <para> - You can also create an array by simply adding values to the - array. When you assign a value to an array variable using empty - brackets, the value will be added onto the end of the array. - <informalexample> - <programlisting role="php"> -$a[] = "hello"; // $a[2] == "hello" -$a[] = "world"; // $a[3] == "world" - </programlisting> - </informalexample> - </para> - <para> - Arrays may be sorted using the <function>asort</function>, - <function>arsort</function>, <function>ksort</function>, - <function>rsort</function>, <function>sort</function>, - <function>uasort</function>, <function>usort</function>, and - <function>uksort</function> functions depending on the type of - sort you want. - </para> - <para> - You can count the number of items in an array using the - <function>count</function> function. - </para> - <para> - You can traverse an array using <function>next</function> and - <function>prev</function> functions. Another common way to - traverse an array is to use the <function>each</function> - function. - </para> - </sect2> - - <sect2 id="language.types.array.multi-dim"> - <title>Multi-Dimensional Arrays</title> - - <para> - Multi-dimensional arrays are actually pretty simple. For each - dimension of the array, you add another [key] value to the end: - <informalexample> - <programlisting role="php"> -$a[1] = $f; # one dimensional examples -$a["foo"] = $f; - -$a[1][0] = $f; # two dimensional -$a["foo"][2] = $f; # (you can mix numeric and associative indices) -$a[3]["bar"] = $f; # (you can mix numeric and associative indices) - -$a["foo"][4]["bar"][0] = $f; # four dimensional! - </programlisting> - </informalexample> - </para> - <para> - In PHP 3 it is not possible to reference multidimensional arrays - directly within strings. For instance, the following will not - have the desired result: - <informalexample> - <programlisting role="php"> -$a[3]['bar'] = 'Bob'; -echo "This won't work: $a[3][bar]"; - </programlisting> - </informalexample> - In PHP 3, the above will output <computeroutput>This won't work: - Array[bar]</computeroutput>. The string concatenation operator, - however, can be used to overcome this: + You should be aware, that array assignment always involves + value copying. You need to use the reference operator to copy + an array by reference. <informalexample> <programlisting role="php"> -$a[3]['bar'] = 'Bob'; -echo "This will work: " . $a[3]['bar']; - </programlisting> - </informalexample> - </para> - <para> - In PHP 4, however, the whole problem may be circumvented by - enclosing the array reference (inside the string) in curly - braces: - <informalexample> - <programlisting role="php"> -$a[3]['bar'] = 'Bob'; -echo "This will work: {$a[3][bar]}"; - </programlisting> - </informalexample> - </para> - <para> - You can "fill up" multi-dimensional arrays in many ways, but the - trickiest one to understand is how to use the - <function>array</function> command for associative arrays. These - two snippets of code fill up the one-dimensional array in the - same way: - <informalexample> - <programlisting role="php"> -# Example 1: - -$a["color"] = "red"; -$a["taste"] = "sweet"; -$a["shape"] = "round"; -$a["name"] = "apple"; -$a[3] = 4; - -# Example 2: -$a = array( - "color" => "red", - "taste" => "sweet", - "shape" => "round", - "name" => "apple", - 3 => 4 -); - </programlisting> - </informalexample> - </para> - <para> - The <function>array</function> function can be nested for - multi-dimensional arrays: - <informalexample> - <programlisting role="php"> -<?php -$a = array( - "apple" => array( - "color" => "red", - "taste" => "sweet", - "shape" => "round" - ), - "orange" => array( - "color" => "orange", - "taste" => "tart", - "shape" => "round" - ), - "banana" => array( - "color" => "yellow", - "taste" => "paste-y", - "shape" => "banana-shaped" - ) -); - -echo $a["apple"]["taste"]; # will output "sweet" -?> +$arr1 = array(2, 3); +$arr2 = $arr1; +$arr2[] = 4; // $arr2 is changed, + // $arr1 is still array(2,3) + +$arr3 = &$arr1; +$arr3[] = 4; // now $arr1 and $arr3 are the same </programlisting> </informalexample> </para> - </sect2> - - --> </sect1> <sect1 id="language.types.object"> @@ -2221,18 +2108,18 @@ integer</link></simpara> </listitem> <listitem> - <simpara><link linkend="language.types.string.casting">Converting to - string</link></simpara> - </listitem> - <!-- don't exist yet - <listitem> <simpara><link linkend="language.types.float.casting">Converting to float</link></simpara> </listitem> <listitem> + <simpara><link linkend="language.types.string.casting">Converting to + string</link></simpara> + </listitem> + <listitem> <simpara><link linkend="language.types.array.casting">Converting to array</link></simpara> </listitem> + <!-- don't exist yet <listitem> <simpara><link linkend="language.types.object.casting">Converting to object</link></simpara> @@ -2248,18 +2135,6 @@ --> </itemizedlist> - </para> - <para> - <!-- TODO: move to 'converting to array' --> - When casting from a scalar or a string variable to an array, the - variable will become the first element of the array: - <informalexample> - <programlisting role="php"> -$var = 'ciao'; -$arr = (array) $var; -echo $arr[0]; // outputs 'ciao' - </programlisting> - </informalexample> </para> <para> <!-- TODO: move to 'converting to object' -->
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php