From 282e5e195e9031c62fd4d38db896f1bdc6f690aa Mon Sep 17 00:00:00 2001
From: Juliette <juxecl@php.net>
Date: Wed, 1 Jul 2009 13:29:56 +0000
Subject: [PATCH] Update ArrayObject skeleton docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@283261 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/arrayobject/append.xml       | 79 ++++++++++++++++++++--
 reference/spl/arrayobject/construct.xml    | 35 +++++++++-
 reference/spl/arrayobject/count.xml        | 49 ++++++++++++--
 reference/spl/arrayobject/offsetexists.xml | 35 ++++++++--
 reference/spl/arrayobject/offsetget.xml    | 35 ++++++++--
 reference/spl/arrayobject/offsetset.xml    | 67 ++++++++++++++++--
 reference/spl/arrayobject/offsetunset.xml  | 34 ++++++++--
 7 files changed, 302 insertions(+), 32 deletions(-)

diff --git a/reference/spl/arrayobject/append.xml b/reference/spl/arrayobject/append.xml
index 32a944ff88..5cea1eca51 100644
--- a/reference/spl/arrayobject/append.xml
+++ b/reference/spl/arrayobject/append.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.append" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::append</refname>
@@ -9,15 +9,34 @@
   &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>ArrayObject::append</methodname>
-   <methodparam><type>mixed</type><parameter>newval</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
   </methodsynopsis>
-
-   &warn.undocumented.func;
+  <para>
+   Appends a new value as the last element.
+  </para>
+  <note>
+   <para>
+    This method cannot be called when the <classname>ArrayObject</classname>
+    was constructed from an object.
+    Use <methodname>ArrayObject::offsetset</methodname> instead.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  &no.function.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>value</parameter></term>
+     <listitem>
+      <para>
+       The value being appended.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -27,6 +46,56 @@
   </para>
  </refsect1>
 
+<refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::append</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arrayobj = new ArrayObject(array('first','second','third'));
+$arrayobj->append('fourth');
+$arrayobj->append(array('five', 'six'));
+var_dump($arrayobj);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+object(ArrayObject)#1 (5) {
+  [0]=>
+  string(5) "first"
+  [1]=>
+  string(6) "second"
+  [2]=>
+  string(5) "third"
+  [3]=>
+  string(6) "fourth"
+  [4]=>
+  array(2) {
+    [0]=>
+    string(4) "five"
+    [1]=>
+    string(3) "six"
+  }
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>ArrayObject::offsetset</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/spl/arrayobject/construct.xml b/reference/spl/arrayobject/construct.xml
index 9fdc110818..f335f456fc 100644
--- a/reference/spl/arrayobject/construct.xml
+++ b/reference/spl/arrayobject/construct.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.construct" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::__construct</refname>
@@ -10,7 +10,9 @@
   &reftitle.description;
   <constructorsynopsis>
    <methodname>ArrayObject::__construct</methodname>
-   <methodparam><type>mixed</type><parameter>input</parameter></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>input</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>iterator_class</parameter></methodparam>
   </constructorsynopsis>
   <para>
    This constructs a new array <type>object</type>. 
@@ -26,7 +28,24 @@
      <listitem>
       <para>
        The <parameter>input</parameter> parameter accepts an 
-       <type>array</type> or another <classname>ArrayObject</classname>.
+       <type>array</type> or an <type>Object</type>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>flags</parameter></term>
+     <listitem>
+      <para>
+       Flags to control the behaviour of the <classname>ArrayObject</classname> object.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>iterator_class</parameter></term>
+     <listitem>
+      <para>
+       Specify the class that will be used for iteration of the <classname>ArrayObject</classname> object.
+       <classname>ArrayIterator</classname> is the default class used.
       </para>
      </listitem>
     </varlistentry>
@@ -75,6 +94,16 @@ object(ArrayObject)#1 (3) {
    </example>
   </para>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>ArrayObject::setflags</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/spl/arrayobject/count.xml b/reference/spl/arrayobject/count.xml
index c6a1f1d73a..376ca3b74a 100644
--- a/reference/spl/arrayobject/count.xml
+++ b/reference/spl/arrayobject/count.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.count" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::count</refname>
-  <refpurpose>Get the number of elements in the Iterator</refpurpose>
+  <refpurpose>Get the number of public properties in the ArrayObject</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -11,8 +11,9 @@
    <type>int</type><methodname>ArrayObject::count</methodname>
    <void/>
   </methodsynopsis>
-
-   &warn.undocumented.func;
+  <para>
+   Get the number of public properties in the <classname>ArrayObject</classname>.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -23,10 +24,48 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The number of elements in the Iterator.
+   The number of public properties in the <classname>ArrayObject</classname>.
   </para>
+  <note>
+   <para>
+    When the <classname>ArrayObject</classname> is constructed from an array all properties are public.
+   </para>
+  </note>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::count</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Example {
+    public $public = 'prop:public';
+    private $prv   = 'prop:private';
+    protected $prt = 'prop:protected';
+}
+
+$arrayobj = new ArrayObject(new Example());
+var_dump($arrayobj->count());
+
+$arrayobj = new ArrayObject(array('first','second','third'));
+var_dump($arrayobj->count());
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+int(1)
+int(3)
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/spl/arrayobject/offsetexists.xml b/reference/spl/arrayobject/offsetexists.xml
index 33f8f41ef8..1010b933bc 100644
--- a/reference/spl/arrayobject/offsetexists.xml
+++ b/reference/spl/arrayobject/offsetexists.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.offsetexists" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::offsetExists</refname>
-  <refpurpose>Returns whether the requested $index exists</refpurpose>
+  <refpurpose>Returns whether the requested index exists</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -11,8 +11,6 @@
    <type>bool</type><methodname>ArrayObject::offsetExists</methodname>
    <methodparam><type>mixed</type><parameter>index</parameter></methodparam>
   </methodsynopsis>
-
-   &warn.undocumented.func;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -34,7 +32,34 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &true; if the requested $index exists, otherwise &false;
+   &true; if the requested index exists, otherwise &false;
+  </para>
+ </refsect1>
+
+  <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::offsetexists</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arrayobj = new ArrayObject(array('zero', 'one', 'example'=>'e.g.'));
+var_dump($arrayobj->offsetexists(1));
+var_dump($arrayobj->offsetexists('example'));
+var_dump($arrayobj->offsetexists('notfound'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+bool(true)
+bool(true)
+bool(false)
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>
 
diff --git a/reference/spl/arrayobject/offsetget.xml b/reference/spl/arrayobject/offsetget.xml
index 3c0685fd52..eae413a781 100644
--- a/reference/spl/arrayobject/offsetget.xml
+++ b/reference/spl/arrayobject/offsetget.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.offsetget" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::offsetGet</refname>
-  <refpurpose>Returns the value at the specified $index</refpurpose>
+  <refpurpose>Returns the value at the specified index</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -11,8 +11,6 @@
    <type>mixed</type><methodname>ArrayObject::offsetGet</methodname>
    <methodparam><type>mixed</type><parameter>index</parameter></methodparam>
   </methodsynopsis>
-
-   &warn.undocumented.func;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -34,7 +32,34 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The value at the specified $index.
+   The value at the specified index or &false;.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::offsetget</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arrayobj = new ArrayObject(array('zero', 7, 'example'=>'e.g.'));
+var_dump($arrayobj->offsetget(1));
+var_dump($arrayobj->offsetget('example'));
+var_dump($arrayobj->offsetexists('notfound'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+int(7)
+string(4) "e.g."
+bool(false)
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>
 
diff --git a/reference/spl/arrayobject/offsetset.xml b/reference/spl/arrayobject/offsetset.xml
index 06b3895a38..965158de2e 100644
--- a/reference/spl/arrayobject/offsetset.xml
+++ b/reference/spl/arrayobject/offsetset.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.offsetset" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::offsetSet</refname>
-  <refpurpose>Sets the value at the specified $index to $newval</refpurpose>
+  <refpurpose>Sets the value at the specified index to newval</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -13,8 +13,6 @@
    <methodparam><type>mixed</type><parameter>newval</parameter></methodparam>
   </methodsynopsis>
 
-  &warn.undocumented.func;
-
   <para>
    Sets the value at the specified index to newval.
   </para>
@@ -51,6 +49,67 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::offsetset</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Example {
+    public $property = 'prop:public';
+}
+$arrayobj = new ArrayObject(new Example());
+$arrayobj->offsetset(4, 'four');
+$arrayobj->offsetset('group', array('g1', 'g2'));
+var_dump($arrayobj);
+
+$arrayobj = new ArrayObject(array('zero','one'));
+$arrayobj->offsetset(null, 'last');
+var_dump($arrayobj);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+object(ArrayObject)#1 (3) {
+  ["property"]=>
+  string(11) "prop:public"
+  [4]=>
+  string(4) "four"
+  ["group"]=>
+  array(2) {
+    [0]=>
+    string(2) "g1"
+    [1]=>
+    string(2) "g2"
+  }
+}
+object(ArrayObject)#3 (3) {
+  [0]=>
+  string(4) "zero"
+  [1]=>
+  string(3) "one"
+  [2]=>
+  string(4) "last"
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>ArrayObject::append</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/spl/arrayobject/offsetunset.xml b/reference/spl/arrayobject/offsetunset.xml
index 0243198a5e..76b97a412a 100644
--- a/reference/spl/arrayobject/offsetunset.xml
+++ b/reference/spl/arrayobject/offsetunset.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="arrayobject.offsetunset" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ArrayObject::offsetUnset</refname>
-  <refpurpose>Unsets the value at the specified $index</refpurpose>
+  <refpurpose>Unsets the value at the specified index</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -11,9 +11,6 @@
    <type>void</type><methodname>ArrayObject::offsetUnset</methodname>
    <methodparam><type>mixed</type><parameter>index</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
   <para>
    Unsets the value at the specified index.
   </para>
@@ -42,6 +39,33 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><methodname>ArrayObject::offsetunset</methodname> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arrayobj = new ArrayObject(array(0=>'zero',2=>'two'));
+$arrayobj->offsetunset(2);
+var_dump($arrayobj);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+object(ArrayObject)#1 (1) {
+  [0]=>
+  string(4) "zero"
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file