From 4d149ee2d53101fe37224715938de2b01cc9923e Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Fri, 28 Nov 2008 21:01:43 +0000
Subject: [PATCH] Initial commit

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@270045 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/predefined/arrayaccess.xml           | 123 ++++++++++++++
 .../predefined/arrayaccess/offsetexists.xml   | 155 ++++++++++++++++++
 language/predefined/arrayaccess/offsetget.xml | 102 ++++++++++++
 language/predefined/arrayaccess/offsetset.xml | 108 ++++++++++++
 .../predefined/arrayaccess/offsetunset.xml    | 105 ++++++++++++
 5 files changed, 593 insertions(+)
 create mode 100644 language/predefined/arrayaccess.xml
 create mode 100644 language/predefined/arrayaccess/offsetexists.xml
 create mode 100644 language/predefined/arrayaccess/offsetget.xml
 create mode 100644 language/predefined/arrayaccess/offsetset.xml
 create mode 100644 language/predefined/arrayaccess/offsetunset.xml

diff --git a/language/predefined/arrayaccess.xml b/language/predefined/arrayaccess.xml
new file mode 100644
index 0000000000..46907d7b8b
--- /dev/null
+++ b/language/predefined/arrayaccess.xml
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<phpdoc:classref xml:id="class.arrayaccess" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The ArrayAccess interface</title>
+ <titleabbrev>ArrayAccess</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ ArrayAccess intro -->
+  <section xml:id="arrayaccess.intro">
+   &reftitle.intro;
+   <para>
+    Interface to provide accessing objects as arrays.
+   </para>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="arrayaccess.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>ArrayAccess</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>ArrayAccess</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+    
+    <classsynopsisinfo role="comment">Methods</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.arrayaccess')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+  <section xml:id="arrayaccess.examples">
+   <example xml:id="arrayaccess.example.basic"><!-- {{{ -->
+    <title>Basic usage</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class obj implements arrayaccess {
+    private $container = array();
+    public function __construct() {
+        $this->container = array(
+            "one"   => 1,
+            "two"   => 2,
+            "three" => 3,
+        );
+    }
+    public function offsetSet($offset, $value) {
+        $this->container[$offset] = $value;
+    }
+    public function offsetExists($offset) {
+        return isset($this->container[$offset]);
+    }
+    public function offsetUnset($offset) {
+        unset($this->container[$offset]);
+    }
+    public function offsetGet($offset) {
+        return isset($this->container[$offset]) ? $this->container[$offset] : null;
+    }
+}
+
+$obj = new obj;
+
+var_dump(isset($obj["two"]));
+var_dump($obj["two"]);
+unset($obj["two"]);
+var_dump(isset($obj["two"]));
+$obj["two"] = "A value";
+var_dump($obj["two"]);
+
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+bool(true)
+int(2)
+bool(false)
+string(7) "A value"
+]]>
+    </screen>
+   </example><!-- }}} -->
+  </section>
+
+ </partintro>
+
+ &language.predefined.arrayaccess.offsetexists;
+ &language.predefined.arrayaccess.offsetget;
+ &language.predefined.arrayaccess.offsetset;
+ &language.predefined.arrayaccess.offsetunset;
+
+</phpdoc:classref>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/arrayaccess/offsetexists.xml b/language/predefined/arrayaccess/offsetexists.xml
new file mode 100644
index 0000000000..9fbb8f8347
--- /dev/null
+++ b/language/predefined/arrayaccess/offsetexists.xml
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<refentry xml:id="arrayaccess.offsetexists" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>ArrayAccess::offsetExists</refname>
+  <refpurpose>Whether a offset exists</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>boolean</type><methodname>ArrayAccess::offsetExists</methodname>
+   <methodparam><type>string</type><parameter>offset</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Whether or not an offset exists.
+  </para>
+  <para>
+   This method is executed when using <function>isset</function> or
+   <function>empty</function> on objects implementing <classname>ArrayAccess</classname>.
+  </para>
+  <note>
+   <para>
+    When using <function>empty</function> <function>ArrayAccess::offsetGet</function> will
+    be called and checked if empty only if <function>ArrayAccess::offsetExists</function>
+    returns <type>true</type>.
+   </para>
+  </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry><term><parameter>offset</parameter></term>
+     <listitem>
+      <para>
+       An offset to check for.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para>
+  <note>
+   <para>
+    The return value will be casted to <type>boolean</type> if non-boolean was returned.
+   </para>
+  </note>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ArrayAccess::offsetExists</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class obj implements arrayaccess {
+    public function offsetSet($offset, $value) {
+        var_dump(__METHOD__);
+    }
+    public function offsetExists($var) {
+        var_dump(__METHOD__);
+        if ($var == "foobar") {
+            return true;
+        }
+        return false;
+    }
+    public function offsetUnset($var) {
+        var_dump(__METHOD__);
+    }
+    public function offsetGet($var) {
+        var_dump(__METHOD__);
+        return "value";
+    }
+}
+
+$obj = new obj;
+
+echo "Runs obj::offsetExists()\n";
+var_dump(isset($obj["foobar"]));
+
+echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
+var_dump(empty($obj["foobar"]));
+
+echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
+var_dump(empty($obj["foobaz"]));
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+Runs obj::offsetExists()
+string(17) "obj::offsetExists"
+bool(true)
+
+Runs obj::offsetExists() and obj::offsetGet()
+string(17) "obj::offsetExists"
+string(14) "obj::offsetGet"
+bool(false)
+
+Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
+string(17) "obj::offsetExists"
+bool(true)
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+
+<!--
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Classname::Method</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+-->
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/arrayaccess/offsetget.xml b/language/predefined/arrayaccess/offsetget.xml
new file mode 100644
index 0000000000..df32845aa8
--- /dev/null
+++ b/language/predefined/arrayaccess/offsetget.xml
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<refentry xml:id="arrayaccess.offsetget" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>ArrayAccess::offsetGet</refname>
+  <refpurpose>Offset to retrieve</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>mixed</type><methodname>ArrayAccess::offsetGet</methodname>
+   <methodparam><type>string</type><parameter>offset</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Returns the value at specified offset.
+  </para>
+  <para>
+   This method is executed when checking if offset is <function>empty</function>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>offset</parameter></term>
+     <listitem>
+      <para>
+       The offset to retrieve.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Can return all value types.
+  </para>
+ </refsect1>
+
+<!--
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ArrayAccess::offsetGet</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/* ... */
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+...
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+-->
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>ArrayAccess::offsetExists</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/arrayaccess/offsetset.xml b/language/predefined/arrayaccess/offsetset.xml
new file mode 100644
index 0000000000..ffc935e5fe
--- /dev/null
+++ b/language/predefined/arrayaccess/offsetset.xml
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<refentry xml:id="arrayaccess.offsetset" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>ArrayAccess::offsetSet</refname>
+  <refpurpose>Offset to set</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>void</type><methodname>ArrayAccess::offsetSet</methodname>
+   <methodparam><type>string</type><parameter>offset</parameter></methodparam>
+   <methodparam><type>string</type><parameter>value</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Assigns a value to the specified offset.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>offset</parameter></term>
+     <listitem>
+      <para>
+       The offset to assign the value to.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>value</parameter></term>
+     <listitem>
+      <para>
+       The value to set.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+<!--
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ArrayAccess::offsetSet</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/* ... */
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+...
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Classname::Method</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+-->
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/language/predefined/arrayaccess/offsetunset.xml b/language/predefined/arrayaccess/offsetunset.xml
new file mode 100644
index 0000000000..ac6a85500a
--- /dev/null
+++ b/language/predefined/arrayaccess/offsetunset.xml
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<refentry xml:id="arrayaccess.offsetunset" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>ArrayAccess::offsetUnset</refname>
+  <refpurpose>Offset to unset</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>abstract</modifier> <modifier>public</modifier> <type>void</type><methodname>ArrayAccess::offsetUnset</methodname>
+   <methodparam><type>string</type><parameter>offset</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Unsets an offset.
+  </para>
+  <note>
+   <para>
+    This method will <emphasis>not</emphasis> be called when type-casting to
+    <link linkend="language.types.typecasting">(unset)</link>
+   </para>
+  </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>offset</parameter></term>
+     <listitem>
+      <para>
+       The offset to unset.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+<!--
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ArrayAccess::offsetUnset</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/* ... */
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+...
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>Classname::Method</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+-->
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->