1Data::Entropy::AlgorithUmsse(r3)Contributed Perl DocumenDtaattai:o:nEntropy::Algorithms(3)
2
3
4

NAME

6       Data::Entropy::Algorithms - basic entropy-using algorithms
7

SYNOPSIS

9               use Data::Entropy::Algorithms
10                       qw(rand_bits rand_int rand_prob);
11
12               $str = rand_bits(17);
13               $i = rand_int(12345);
14               $i = rand_int(Math::BigInt->new("1000000000000"));
15               $j = rand_prob(1, 2, 3);
16               $j = rand_prob([ 1, 2, 3 ]);
17
18               use Data::Entropy::Algorithms qw(rand_fix rand rand_flt);
19
20               $x = rand_fix(48);
21               $x = rand(7);
22               $x = rand_flt(0.0, 7.0);
23
24               use Data::Entropy::Algorithms
25                       qw(pick pick_r choose choose_r shuffle shuffle_r);
26
27               $item = pick($item0, $item1, $item2);
28               $item = pick_r(\@items);
29               @chosen = choose(3, $item0, $item1, $item2, $item3, $item4);
30               $chosen = choose_r(3, \@items);
31               @shuffled = shuffle($item0, $item1, $item2, $item3, $item4);
32               $shuffled = shuffle_r(\@items);
33

DESCRIPTION

35       This module contains a collection of fundamental algorithms that use
36       entropy.  They all use the entropy source mechanism described in
37       Data::Entropy.
38

FUNCTIONS

40       All of these functions use entropy.  The entropy source is not an
41       explicit input in any case.  All functions use the current entropy
42       source maintained by the "Data::Entropy" module.  To select an entropy
43       source use the "with_entropy_source" function in that module, or
44       alternatively do nothing to use the default source.
45
46   Fundamental entropy extraction
47       rand_bits(NBITS)
48           Returns NBITS bits of entropy, as a string of octets.  If NBITS is
49           not a multiple of eight then the last octet in the string has its
50           most significant bits set to zero.
51
52       rand_int(LIMIT)
53           LIMIT must be a positive integer.  Returns a uniformly-distributed
54           random integer in the range [0, LIMIT).  LIMIT may be either a
55           native integer, a "Math::BigInt" object, or an integer-valued
56           "Math::BigRat" object; the returned number is of the same type.
57
58       rand_prob(PROB ...)
59       rand_prob(PROBS)
60           Returns a random integer selected with non-uniform probability.
61           The relative probabilities are supplied as a list of non-negative
62           integers (multiple PROB arguments) or a reference to an array of
63           integers (the PROBS argument).  The relative probabilities may be
64           native integers, "Math::BigInt" objects, or integer-valued
65           "Math::BigRat" objects; they must all be of the same type.  At
66           least one probability value must be positive.
67
68           The first relative probability value (the first PROB or the first
69           element of PROBS) is the relative probability of returning 0.  The
70           absolute probability of returning 0 is this value divided by the
71           total of all the relative probability values.  Similarly the second
72           value controls the probability of returning 1, and so on.
73
74   Numbers
75       rand_fix(NBITS)
76           Returns a uniformly-distributed random NBITS-bit fixed-point
77           fraction in the range [0, 1).  That is, the result is a randomly-
78           chosen multiple of 2^-NBITS, the multiplier being a random integer
79           in the range [0, 2^NBITS).  The value is returned in the form of a
80           native floating point number, so NBITS can be at most one greater
81           than the number of bits of significand in the floating point
82           format.
83
84           With NBITS = 48 the range of output values is the same as that of
85           the Unix "drand48" function.
86
87       rand([LIMIT])
88           Generates a random fixed-point fraction by "rand_fix" and then
89           multiplies it by LIMIT, returning the result.  LIMIT defaults to 1,
90           and if it is 0 then that is also treated as 1.  The length of the
91           fixed-point fraction is 48 bits, unless that can't be represented
92           in the native floating point type, in which case the longest
93           possible fraction will be generated instead.
94
95           This is a drop-in replacement for "CORE::rand": it produces exactly
96           the same range of output values, but using the current entropy
97           source instead of a sucky PRNG with linear relationships between
98           successive outputs.  ("CORE::rand" does the type of calculation
99           described, but using the PRNG "drand48" to generate the fixed-point
100           fraction.)  The details of behaviour may change in the future if
101           the behaviour of "CORE::rand" changes, to maintain the match.
102
103           Where the source of a module can't be readily modified, it can be
104           made to use this "rand" by an incantation such as
105
106                   *Foreign::Module::rand = \&Data::Entropy::Algorithms::rand;
107
108           This must be done before the module is loaded, most likely in a
109           "BEGIN" block.  It is also possible to override "CORE::rand" for
110           all modules, by performing this similarly early:
111
112                   *CORE::GLOBAL::rand = \&Data::Entropy::Algorithms::rand;
113
114           This function should not be used in any new code, because the kind
115           of output supplied by "rand" is hardly ever the right thing to use.
116           The "int(rand($n))" idiom to generate a random integer has non-
117           uniform probabilities of generating each possible value, except
118           when $n is a power of two.  For floating point numbers, "rand"
119           can't generate most representable numbers in its output range, and
120           the output is biased towards zero.  In new code use "rand_int" to
121           generate integers and "rand_flt" to generate floating point
122           numbers.
123
124       rand_flt(MIN, MAX)
125           Selects a uniformly-distributed real number (with infinite
126           precision) in the range [MIN, MAX] and then rounds this number to
127           the nearest representable floating point value, which it returns.
128           (Actually it is only as if the function worked this way: in fact it
129           never generates the number with infinite precision.  It selects
130           between the representable floating point values with the
131           probabilities implied by this process.)
132
133           This can return absolutely any floating point value in the range
134           [MIN, MAX]; both MIN and MAX themselves are possible return values.
135           All bits of the floating point type are filled randomly, so the
136           range of values that can be returned depends on the details of the
137           floating point format.  (See Data::Float for low-level floating
138           point utilities.)
139
140           The function "die"s if MIN and MAX are not both finite.  If MIN is
141           greater than MAX then their roles are swapped: the order of the
142           limit parameters actually doesn't matter.  If the limits are
143           identical then that value is always returned.  As a special case,
144           if the limits are positive zero and negative zero then a zero will
145           be returned with a randomly-chosen sign.
146
147   Combinatorics
148       pick(ITEM ...)
149           Randomly selects and returns one of the ITEMs.  Each ITEM has equal
150           probability of being selected.
151
152       pick_r(ITEMS)
153           ITEMS must be a reference to an array.  Randomly selects and
154           returns one of the elements of the array.  Each element has equal
155           probability of being selected.
156
157           This is the same operation as that performed by "pick", but using
158           references to avoid expensive copying of arrays.
159
160       choose(NCHOOSE, ITEM ...)
161           Randomly selects NCHOOSE of the ITEMs.  Each ITEM has equal
162           probability of being selected.  The chosen items are returned in a
163           list in the same order in which they appeared in the argument list.
164
165       choose_r(NCHOOSE, ITEMS)
166           ITEMS must be a reference to an array.  Randomly selects NCHOOSE of
167           the elements in the array.  Each element has equal probability of
168           being selected.  Returns a reference to an array containing the
169           chosen items in the same order in which they appeared in the input
170           array.
171
172           This is the same operation as that performed by "choose", but using
173           references to avoid expensive copying of arrays.
174
175       shuffle(ITEM ...)
176           Reorders the ITEMs randomly, and returns them in a list in random
177           order.  Each possible order has equal probability.
178
179       shuffle_r(ITEMS)
180           ITEMS must be a reference to an array.  Reorders the elements of
181           the array randomly.  Each possible order has equal probability.
182           Returns a reference to an array containing the elements in random
183           order.
184
185           This is the same operation as that performed by "shuffle", but
186           using references to avoid expensive copying of arrays.
187

SEE ALSO

189       Data::Entropy, Data::Entropy::Source
190

AUTHOR

192       Andrew Main (Zefram) <zefram@fysh.org>
193
195       Copyright (C) 2006, 2007, 2009, 2011 Andrew Main (Zefram)
196       <zefram@fysh.org>
197

LICENSE

199       This module is free software; you can redistribute it and/or modify it
200       under the same terms as Perl itself.
201
202
203
204perl v5.36.0                      2023-01-20      Data::Entropy::Algorithms(3)
Impressum