1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
<?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.
</para>
&caution.cryptographically-insecure;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
Cannot be empty.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>num</parameter></term>
<listitem>
<para>
Specifies how many entries should be picked.
Must be greater than zero, and less than or equal to the length of <parameter>array</parameter>
</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.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws a <classname>ValueError</classname> if <parameter>array</parameter> is empty,
or if <parameter>num</parameter> is out of range.
</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>8.0.0</entry>
<entry>
<function>array_rand</function> now throws a <classname>ValueError</classname>
if <parameter>num</parameter> is out of range; previously an
<constant>E_WARNING</constant> was raised, and the function returned &null;.
</entry>
</row>
<row>
<entry>8.0.0</entry>
<entry>
<function>array_rand</function> now throws a <classname>ValueError</classname>
if <parameter>array</parameter> is empty; previously an
<constant>E_WARNING</constant> was raised, and the function returned &null;.
</entry>
</row>
<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>Random\Randomizer::pickArrayKeys</function></member>
<member><function>Random\Randomizer::shuffleArray</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
-->
|
