php-doc-en/reference/array/functions/array-rand.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.array-rand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>array_rand</refname>
  <refpurpose>Pick one or more random keys out of an array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>string</type><type>array</type></type><methodname>array_rand</methodname>
   <methodparam><type>array</type><parameter>array</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num</parameter><initializer>1</initializer></methodparam>
  </methodsynopsis>
  <para>
   Picks one or more random entries out of an array, and returns the
   key (or keys) of the random entries.
   It uses a pseudo random number generator that is not suitable for
   cryptographic purposes.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       The input array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
      <para>
       Specifies how many entries should be picked.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   When picking only one entry, <function>array_rand</function> returns
   the key for a random entry. Otherwise, an array of keys for the random
   entries is returned. This is done so that random keys can be picked
   from the array as well as random values. If multiple keys are returned,
   they will be returned in the order they were present in the original array.
   Trying to pick more elements
   than there are in the array will result in an
   <constant>E_WARNING</constant> level error, and NULL will be returned.
  </para>
 </refsect1>
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.1.0</entry>
       <entry>
        The internal randomization algorithm <link linkend="migration71.incompatible.rand-srand-aliases">has been changed</link> to use the <link xlink:href="&url.mersenne;">Mersenne Twister</link> Random Number Generator instead of the libc rand function.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>array_rand</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
$rand_keys = array_rand($input, 2);
echo $input[$rand_keys[0]] . "\n";
echo $input[$rand_keys[1]] . "\n";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>shuffle</function></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:"~/.phpdoc/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
-->