From db8088a4bceca06fff66f246b5f4247ed155f0c8 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Fri, 18 Jul 2003 08:31:09 +0000
Subject: [PATCH] Properly document the word "element" as an array key/value
 pair, and "value" as the value.  This almost closes bug #20394

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@135353 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/array/functions/current.xml | 24 +++++++++++++++++++++---
 reference/array/functions/end.xml     |  5 +++--
 reference/array/functions/next.xml    | 26 +++++++++++++++++++++-----
 reference/array/functions/prev.xml    | 21 +++++++++++++++++++--
 4 files changed, 64 insertions(+), 12 deletions(-)

diff --git a/reference/array/functions/current.xml b/reference/array/functions/current.xml
index 8ddb7c5c92..eecf044969 100644
--- a/reference/array/functions/current.xml
+++ b/reference/array/functions/current.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.current">
    <refnamediv>
@@ -19,8 +19,8 @@
     </para>
     <para>
      The <function>current</function> function simply returns the
-     array element that's currently being pointed by the internal
-     pointer.  It does not move the pointer in any way.  If the
+     value of the array element that's currently being pointed to by the
+     internal pointer.  It does not move the pointer in any way.  If the
      internal pointer points beyond the end of the elements list,
      <function>current</function> returns &false;.
      <warning>
@@ -35,6 +35,24 @@
       </para>
      </warning>
     </para>
+    <para>
+     <example>
+      <title>Example use of <function>current</function> and friends</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$transport = array('foot', 'bike', 'car', 'plane');
+$mode = current($transport); // $mode = 'foot';
+$mode = next($transport);    // $mode = 'bike';
+$mode = current($transport); // $mode = 'bike';
+$mode = prev($transport);    // $mode = 'foot';
+$mode = end($transport);     // $mode = 'plane';
+$mode = current($transport); // $mode = 'plane';
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      See also <function>end</function>, <function>key</function>,
      <function>next</function>, <function>prev</function>, and
diff --git a/reference/array/functions/end.xml b/reference/array/functions/end.xml
index 1e3c218500..dba5d33128 100644
--- a/reference/array/functions/end.xml
+++ b/reference/array/functions/end.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.end">
    <refnamediv>
@@ -16,7 +16,8 @@
      </methodsynopsis>
     <para>
      <function>end</function> advances <parameter>array</parameter>'s
-     internal pointer to the last element, and returns that element.
+     internal pointer to the last element, and returns the value from
+     the last element.
     </para>
     <para>
      <example>
diff --git a/reference/array/functions/next.xml b/reference/array/functions/next.xml
index 0c55e2fcb7..bc53b884f0 100644
--- a/reference/array/functions/next.xml
+++ b/reference/array/functions/next.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.next">
    <refnamediv>
@@ -15,15 +15,14 @@
       <methodparam><type>array</type><parameter>array</parameter></methodparam>
      </methodsynopsis>
     <para>
-     Returns the array element in the next place that's pointed by the
-     internal array pointer, or &false; if
-     there are no more elements.
+     Returns the array value in the next place that's pointed to by the
+     internal array pointer, or &false; if there are no more elements.
     </para>
     <para>
      <function>next</function> behaves like
      <function>current</function>, with one difference.  It advances
      the internal array pointer one place forward before returning the
-     element.  That means it returns the next array element and
+     element value.  That means it returns the next array value and
      advances the internal array pointer by one.  If advancing the
      internal array pointer results in going beyond the end of the
      element list, <function>next</function> returns &false;.
@@ -37,6 +36,23 @@
       </para>
      </warning>
     </para>
+    <para>
+     <example>
+      <title>Example use of <function>next</function> and friends</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$transport = array('foot', 'bike', 'car', 'plane');
+$mode = current($transport); // $mode = 'foot';
+$mode = next($transport);    // $mode = 'bike';
+$mode = next($transport);    // $mode = 'car';
+$mode = prev($transport);    // $mode = 'bike';
+$mode = end($transport);     // $mode = 'plane';
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      See also
      <function>current</function>, <function>end</function>,
diff --git a/reference/array/functions/prev.xml b/reference/array/functions/prev.xml
index 8b53e59916..4f337902e4 100644
--- a/reference/array/functions/prev.xml
+++ b/reference/array/functions/prev.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.prev">
    <refnamediv>
@@ -13,7 +13,7 @@
       <methodparam><type>array</type><parameter>array</parameter></methodparam>
      </methodsynopsis>
     <para>
-     Returns the array element in the previous place that's pointed by
+     Returns the array value in the previous place that's pointed to by
      the internal array pointer, or &false; if there are no more
      elements.
      <warning>
@@ -30,6 +30,23 @@
      <function>next</function>, except it rewinds the internal array
      pointer one place instead of advancing it.
     </para>
+    <para>
+     <example>
+      <title>Example use of <function>prev</function> and friends</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$transport = array('foot', 'bike', 'car', 'plane');
+$mode = current($transport); // $mode = 'foot';
+$mode = next($transport);    // $mode = 'bike';
+$mode = next($transport);    // $mode = 'car';
+$mode = prev($transport);    // $mode = 'bike';
+$mode = end($transport);     // $mode = 'plane';
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      See also <function>current</function>, <function>end</function>,
      <function>next</function>, and <function>reset</function>.