torben Wed Jun 18 13:59:25 2003 EDT
Modified files:
/phpdoc/en/language types.xml
Log:
Some grammar and factual fixes.
Index: phpdoc/en/language/types.xml
diff -u phpdoc/en/language/types.xml:1.115 phpdoc/en/language/types.xml:1.116
--- phpdoc/en/language/types.xml:1.115 Sat Jun 14 00:00:55 2003
+++ phpdoc/en/language/types.xml Wed Jun 18 13:59:25 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.115 $ -->
+<!-- $Revision: 1.116 $ -->
<chapter id="language.types">
<title>Types</title>
@@ -1239,12 +1239,12 @@
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
+ PHP array as a value, you can also quite easily simulate
trees.
</para>
<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.
+ 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.
</para>
@@ -1263,13 +1263,11 @@
</para>
<para>
<synopsis>
-array( <optional> <replaceable>key</replaceable> => </optional> <replaceable
->value</replaceable>
+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
+// <replaceable>key</replaceable> may be an <type>integer</type> or
<type>string</type>
+// <replaceable>value</replaceable> may be any value
</synopsis>
</para>
<para>
@@ -1287,14 +1285,14 @@
</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>). 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 <varname>key</varname> may be either an integer
+ <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 of any PHP type.
@@ -1313,13 +1311,14 @@
</informalexample>
</para>
<para>
- If you omit a key, the maximum of the integer-indices is taken, and
- the new key will be that maximum + 1. As integers can be negative,
- this is also true for negative indices. Having e.g. the highest index
- being <literal>-6</literal> will result in <literal>-5</literal> being
- 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.
+ If you provide the brackets without specifying a key, then the
+ maximum of the integer indices is taken, and the new key will be
+ that maximum value + 1--unless that maximum value is negative
+ (is it perfectly legal to have negative array indices). In this
+ case, the new key will be <literal>0</literal>. 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[
@@ -1335,13 +1334,13 @@
</informalexample>
</para>
<para>
- Using &true; as a key will evalute to
- <type>integer</type> <literal>1</literal> as key. Using
- &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.
+ Using &true; as a key will evaluate to <type>integer</type>
+ <literal>1</literal> as key. Using &false; as a key will evaluate
+ to <type>integer</type> <literal>0</literal> as key. Using
+ <literal>NULL</literal> 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.
</para>
<para>
You cannot use arrays or objects as keys. Doing so will result in a
@@ -1352,19 +1351,18 @@
<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
+ You can also modify an existing array by explicitly setting
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
- of brackets ("<literal>[]</literal>") to the variable-name in that case.
+ of brackets ("<literal>[]</literal>") to the variable name in that case.
<synopsis>
$arr[<replaceable>key</replaceable>] = <replaceable>value</replaceable>;
$arr[] = <replaceable>value</replaceable>;
-// <replaceable>key</replaceable> is either <type>string</type
- > or nonnegative <type>integer</type>
-// <replaceable>value</replaceable> can be anything
+// <replaceable>key</replaceable> may be an <type>integer</type> or
<type>string</type>
+// <replaceable>value</replaceable> may be any value
</synopsis>
If <varname>$arr</varname> doesn't exist yet, it will be created.
So this is also an alternative way to specify an array.
@@ -1393,23 +1391,78 @@
</para>
<note>
<para>
- If you omit a key, the maximum of the integer-indices is taken, and
- the new key will be that maximum + 1.
- Note that the maximum is same when the element having
- maximum-index was cleared using <function>unset</function> function.
- <informalexample>
- <programlisting role="php">
+ 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--unless
+ that maximum value is negative (is it perfectly legal to have
+ negative array indices). In this case, the new key will be
+ <literal>0</literal>. 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.
+ </para>
+ <para>
+ Note that the maximum integer key used for this <emphasis>need
+ not currently exist in the array</emphasis>. It simply must
+ have existed in the array at some time since the last time the
+ array was re-indexed. The following example illustrates:
+ </para>
+
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-$a = array("orange","apple","banana");
-unset($a[2]); // clear $a[2]
-$a[] = 'carrot'; // assign a new value without key
-var_dump($a); // output: array(0 => 'orange', 1 => 'apple', 3 => 'carrot')
+// Create a simple array.
+$array = array(1, 2, 3, 4, 5);
+print_r($array);
+
+// Now delete every item, but leave the array itself intact:
+foreach ($array as $i => $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);
?>
]]>
- </programlisting>
- </informalexample>
- </para>
+ </programlisting>
+ <para>
+ The above example would produce the following output:
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => 1
+ [1] => 2
+ [2] => 3
+ [3] => 4
+ [4] => 5
+)
+Array
+(
+)
+Array
+(
+ [5] => 6
+)
+Array
+(
+ [0] => 6
+ [1] => 7
+)
+]]>
+ </screen>
+ </para>
+ </informalexample>
+
</note>
</sect3>
</sect2><!-- end syntax -->
@@ -1417,9 +1470,8 @@
<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.
+ There are quite a few useful functions for working with arrays.
+ See the <link linkend="ref.array">array functions</link> section.
</para>
<note>
<para>
@@ -1826,7 +1878,7 @@
<function>count</function> function.
</para>
<example>
- <title>Sorting array</title>
+ <title>Sorting an array</title>
<programlisting role="php">
<