-
Notifications
You must be signed in to change notification settings - Fork 860
Expand file tree
/
Copy pathgenerate.xml
More file actions
160 lines (146 loc) · 4.97 KB
/
generate.xml
File metadata and controls
160 lines (146 loc) · 4.97 KB
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
152
153
154
155
156
157
158
159
160
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="random-engine.generate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Random\Engine::generate</refname>
<refpurpose>Generates randomness</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="Random\\Engine">
<modifier>public</modifier> <type>string</type><methodname>Random\Engine::generate</methodname>
<void/>
</methodsynopsis>
<para>
Returns randomness and advances the algorithm’s state by one step.
</para>
<para>
The randomness is represented by a binary string containing random bytes. This representation
allows to unambiguously interpret the random bits generated by the algorithm, for example to
accomodate different output sizes used by different algorithms.
</para>
<para>
Algorithms that natively operate on integer values should return the integer in little-endian
byte order, for example by leveraging the <function>pack</function> function with the
<literal>P</literal> format code. The high-level interface provided by the
<classname>Random\Randomizer</classname> will interpret the returned random bytes as unsigned
little-endian integers if a numeric representation is required.
</para>
<para>
It is strongly recommended that each bit of the returned string is uniformly and independently
selected, as some applications require randomness based on the bit-level to work correctly.
For example linear congruential generators often generate lower-quality randomness for the less
significant bits of the return integer value and thus would not be appropriate for applications
that require bit-level randomness.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
A non-empty string containing random bytes.
</para>
<note>
<simpara>
The <classname>Random\Randomizer</classname> works with unsigned 64 bit integers internally.
If the returned string contains more than 64 bit (8 byte) of randomness the exceeding
bytes will be ignored. Other applications may be able to process more than 64 bit at once.
</simpara>
</note>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<itemizedlist>
<listitem>
<simpara>
If generating randomness fails, a <classname>Random\RandomException</classname> should
be thrown. Any other <classname>Exception</classname> thrown during generation should
be caught and wrapped into a <classname>Random\RandomException</classname>.
</simpara>
</listitem>
<listitem>
<simpara>
If the returned string is empty, a <classname>Random\BrokenRandomEngineError</classname>
will be thrown by the <classname>Random\Randomizer</classname>.
</simpara>
</listitem>
<listitem>
<simpara>
If the implemented algorithm is severely biased, a <classname>Random\BrokenRandomEngineError</classname>
may be thrown by the <classname>Random\Randomizer</classname> to prevent infinite loops
if rejection sampling is required to return unbiased results.
</simpara>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Random\Engine::generate</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
/**
* Implements a Linear Congruential Generator with modulus 65536,
* multiplier 61 and increment 17 returning an 8 Bit integer.
*
* Note: This engine is suitable for demonstration purposes only.
* Linear Congruential Generators generally generate low
* quality randomness and this specific implementation has
* a very short 16 Bit period that is unsuitable for
* almost any real-world use case.
*/
final class LinearCongruentialGenerator implements \Random\Engine
{
private int $state;
public function __construct(?int $seed = null)
{
if ($seed === null) {
$seed = random_int(0, 0xffff);
}
$this->state = $seed & 0xffff;
}
public function generate(): string
{
$this->state = (61 * $this->state + 17) & 0xffff;
return pack('C', $this->state >> 8);
}
}
$r = new \Random\Randomizer(
new LinearCongruentialGenerator(seed: 1)
);
echo "Lucky Number: ", $r->getInt(0, 99), "\n";
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Lucky Number: 4
]]>
</screen>
</example>
</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
-->