[PHP-DOC] cvs: phpdoc /en/functions array.xml From: Andrei Zmievski (andrei <email protected>)
Date: 07/11/00

andrei Tue Jul 11 12:54:49 2000 EDT

  Modified files:
    /phpdoc/en/functions array.xml
  Log:
  Docs for array_rand().
  
  
Index: phpdoc/en/functions/array.xml
diff -u phpdoc/en/functions/array.xml:1.12 phpdoc/en/functions/array.xml:1.13
--- phpdoc/en/functions/array.xml:1.12 Tue Jul 11 12:33:04 2000
+++ phpdoc/en/functions/array.xml Tue Jul 11 12:54:49 2000
@@ -208,12 +208,10 @@
        "b", "shape" => "trapezoid", 4).
       </para>
      </example>
- <note>
- <para>
- This function was added in PHP 4.0.
- </para>
- </note>
     </para>
+ <para>
+ See also <function>array_merge_recursive</function>.
+ </para>
    </refsect1>
   </refentry>
 
@@ -261,6 +259,9 @@
       </para>
      </example>
     </para>
+ <para>
+ See also <function>array_merge</function>.
+ </para>
    </refsect1>
   </refentry>
 
@@ -523,6 +524,57 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.array-rand">
+ <refnamediv>
+ <refname>array_rand</refname>
+ <refpurpose>Pick one or more random entries out of an array</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>mixed <function>array_rand</function></funcdef>
+ <paramdef>array <parameter>input</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>num_req</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>array_rand</function> is rather useful when you want to
+ pick one or more random entries out of an array. It takes an
+ <parameter>input</parameter> array and an optional argument
+ <parameter>num_req</parameter> which specifies how many entries you
+ want to pick - if not specified, it defaults to 1.
+ </para>
+
+ <para>
+ If you are picking only one entry, <function>array_rand</function>
+ returns the key for a random entry. Otherwise, it returns an array
+ of keys for the random entries. This is done so that you can pick
+ random keys as well as values out of the array.
+ </para>
+
+ <para>
+ Don't forget to call <function>srand</function> to seed the random
+ number generator.
+ </para>
+
+ <para>
+ <example>
+ <title><function>array_rand</function> example</title>
+ <programlisting role="php">
+srand((double)microtime() * 10000000);
+$input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
+$rand_keys = array_rand($input, 2);
+print $input[$rand_keys[0]]."\n";
+print $input[$rand_keys[1]]."\n";
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.array-reverse">
    <refnamediv>
     <refname>array_reverse</refname>