Documentation for SplObjectStorage::getHash().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@319549 c90b9560-bf6c-de11-be94-00142212c4b1

reference/spl/splobjectstorage/gethash.xml

@@ -4,7 +4,9 @@
 <refentry xml:id="splobjectstorage.gethash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>SplObjectStorage::getHash</refname>
-  <refpurpose>Returns the hash of an object</refpurpose>
+  <refpurpose>
+   Calculate an unique identifier for the contained objects
+  </refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,10 +16,20 @@
    <methodparam><type>string</type><parameter>object</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   The function calculates an identifier for the objects added to this
+   <classname>SplObjectStorage</classname> object.
+  </para>
+  <para>
+   The implementation in <classname>SplObjectStorage</classname> returns
+   the same value as <function>spl_object_hash</function>.
+  </para>
+  <para>
+   This identifer must unique among the objects contained. This means this
+   object will never contain more than one object with the same identifier.
+   As such, it can be used to implement a set (a collection of unique values)
+   where the quality of an object being unique is determined by the value
+   returned by this function being unique.
   </para>
-
-  &warn.undocumented.func;
 
  </refsect1>
 
@@ -28,7 +40,7 @@
     <term><parameter>object</parameter></term>
     <listitem>
      <para>
-      
+      The object whose identifier is to be calculated.
      </para>
     </listitem>
    </varlistentry>
@@ -38,10 +50,54 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   A <type>string</type> with the calculated identifier. An exception is
+   thrown if any other type is returned.
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>SplObjectStorage::getHash</function> example</title>
+<programlisting role="php">
+<![CDATA[
+<?php
+class OneSpecimenPerClassStorage extends SplObjectStorage {
+            public function getHash($o) {
+                            return get_class($o);
+                                }
+}
+class A {}
 
+$s = new OneSpecimenPerClassStorage;
+$o1 = new stdclass;
+$o2 = new stdclass;
+$o3 = new A;
+
+$s[$o1] = 1;
+//$o2 is considered equal to $o1 so the value is replaced
+$s[$o2] = 2;
+$s[$o3] = 3;
+
+//these are considered equal to the objects before
+//so they can be used to access the values stored under them
+$p1 = new stdclass;
+$p2 = new A;
+echo $s[$p1], "\n";
+echo $s[$p2], "\n";
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+2
+3
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
 
 </refentry>