reference/array/functions/array-rand.xml
4a1dedc24b1e085f298ab1d5dadefe306373691b
4a1dedc24b1e085f298ab1d5dadefe306373691b
...
...
@@ -1,23 +1,22 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.array-rand" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.array-rand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>array_rand</refname>
6
-
<refpurpose>Pick one or more random entries out of an array</refpurpose>
6
+
<refpurpose>Pick one or more random keys out of an array</refpurpose>
7
7
</refnamediv>
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
-
<type>mixed</type><methodname>array_rand</methodname>
11
+
<type class="union"><type>int</type><type>string</type><type>array</type></type><methodname>array_rand</methodname>
12
12
<methodparam><type>array</type><parameter>array</parameter></methodparam>
13
13
<methodparam choice="opt"><type>int</type><parameter>num</parameter><initializer>1</initializer></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
16
Picks one or more random entries out of an array, and returns the
17
17
key (or keys) of the random entries.
18
-
It uses a pseudo random number generator that is not suitable for
19
-
cryptographic purposes.
20
18
</para>
19
+
&caution.cryptographically-insecure;
21
20
</refsect1>
22
21
<refsect1 role="parameters">
23
22
&reftitle.parameters;
...
...
@@ -28,6 +27,7 @@
28
27
<listitem>
29
28
<para>
30
29
The input array.
30
+
Cannot be empty.
31
31
</para>
32
32
</listitem>
33
33
</varlistentry>
...
...
@@ -36,6 +36,7 @@
36
36
<listitem>
37
37
<para>
38
38
Specifies how many entries should be picked.
39
+
Must be greater than zero, and less than or equal to the length of <parameter>array</parameter>
39
40
</para>
40
41
</listitem>
41
42
</varlistentry>
...
...
@@ -48,11 +49,19 @@
48
49
When picking only one entry, <function>array_rand</function> returns
49
50
the key for a random entry. Otherwise, an array of keys for the random
50
51
entries is returned. This is done so that random keys can be picked
51
-
from the array as well as random values. Trying to pick more elements
52
-
than there are in the array will result in an
53
-
<constant>E_WARNING</constant> level error, and NULL will be returned.
52
+
from the array as well as random values. If multiple keys are returned,
53
+
they will be returned in the order they were present in the original array.
54
54
</para>
55
55
</refsect1>
56
+
57
+
<refsect1 role="errors">
58
+
&reftitle.errors;
59
+
<para>
60
+
Throws a <classname>ValueError</classname> if <parameter>array</parameter> is empty,
61
+
or if <parameter>num</parameter> is out of range.
62
+
</para>
63
+
</refsect1>
64
+
56
65
<refsect1 role="changelog">
57
66
&reftitle.changelog;
58
67
<para>
...
...
@@ -66,9 +75,25 @@
66
75
</thead>
67
76
<tbody>
68
77
<row>
69
-
<entry>5.2.10</entry>
78
+
<entry>8.0.0</entry>
79
+
<entry>
80
+
<function>array_rand</function> now throws a <classname>ValueError</classname>
81
+
if <parameter>num</parameter> is out of range; previously an
82
+
<constant>E_WARNING</constant> was raised, and the function returned &null;.
83
+
</entry>
84
+
</row>
85
+
<row>
86
+
<entry>8.0.0</entry>
70
87
<entry>
71
-
The resulting array of keys is no longer shuffled.
88
+
<function>array_rand</function> now throws a <classname>ValueError</classname>
89
+
if <parameter>array</parameter> is empty; previously an
90
+
<constant>E_WARNING</constant> was raised, and the function returned &null;.
91
+
</entry>
92
+
</row>
93
+
<row>
94
+
<entry>7.1.0</entry>
95
+
<entry>
96
+
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.
72
97
</entry>
73
98
</row>
74
99
</tbody>
...
...
@@ -98,12 +123,12 @@ echo $input[$rand_keys[1]] . "\n";
98
123
&reftitle.seealso;
99
124
<para>
100
125
<simplelist>
101
-
<member><function>shuffle</function></member>
126
+
<member><function>Random\Randomizer::pickArrayKeys</function></member>
127
+
<member><function>Random\Randomizer::shuffleArray</function></member>
102
128
</simplelist>
103
129
</para>
104
130
</refsect1>
105
131
</refentry>
106
-
107
132
<!-- Keep this comment at the end of the file
108
133
Local variables:
109
134
mode: sgml
110
135