.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Entropy::Algorithms 3pm"
.TH Data::Entropy::Algorithms 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Entropy::Algorithms \- basic entropy\-using algorithms
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&        use Data::Entropy::Algorithms
\&                qw(rand_bits rand_int rand_prob);
\&
\&        $str = rand_bits(17);
\&        $i = rand_int(12345);
\&        $i = rand_int(Math::BigInt\->new("1000000000000"));
\&        $j = rand_prob(1, 2, 3);
\&        $j = rand_prob([ 1, 2, 3 ]);
\&
\&        use Data::Entropy::Algorithms qw(rand_fix rand rand_flt);
\&
\&        $x = rand_fix(48);
\&        $x = rand(7);
\&        $x = rand_flt(0.0, 7.0);
\&
\&        use Data::Entropy::Algorithms
\&                qw(pick pick_r choose choose_r shuffle shuffle_r);
\&
\&        $item = pick($item0, $item1, $item2);
\&        $item = pick_r(\e@items);
\&        @chosen = choose(3, $item0, $item1, $item2, $item3, $item4);
\&        $chosen = choose_r(3, \e@items);
\&        @shuffled = shuffle($item0, $item1, $item2, $item3, $item4);
\&        $shuffled = shuffle_r(\e@items);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module contains a collection of fundamental algorithms that
use entropy.  They all use the entropy source mechanism described in
Data::Entropy.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
All of these functions use entropy.  The entropy source is not an
explicit input in any case.  All functions use the current entropy source
maintained by the \f(CW\*(C`Data::Entropy\*(C'\fR module.  To select an entropy source
use the \f(CW\*(C`with_entropy_source\*(C'\fR function in that module, or alternatively
do nothing to use the default source.
.SS "Fundamental entropy extraction"
.IX Subsection "Fundamental entropy extraction"
.IP "rand_bits(\s-1NBITS\s0)" 4
.IX Item "rand_bits(NBITS)"
Returns \s-1NBITS\s0 bits of entropy, as a string of octets.  If \s-1NBITS\s0 is
not a multiple of eight then the last octet in the string has its most
significant bits set to zero.
.IP "rand_int(\s-1LIMIT\s0)" 4
.IX Item "rand_int(LIMIT)"
\&\s-1LIMIT\s0 must be a positive integer.  Returns a uniformly-distributed random
integer in the range [0, \s-1LIMIT\s0).  \s-1LIMIT\s0 may be either a native integer,
a \f(CW\*(C`Math::BigInt\*(C'\fR object, or an integer-valued \f(CW\*(C`Math::BigRat\*(C'\fR object;
the returned number is of the same type.
.IP "rand_prob(\s-1PROB ...\s0)" 4
.IX Item "rand_prob(PROB ...)"
.PD 0
.IP "rand_prob(\s-1PROBS\s0)" 4
.IX Item "rand_prob(PROBS)"
.PD
Returns a random integer selected with non-uniform probability.  The
relative probabilities are supplied as a list of non-negative integers
(multiple \s-1PROB\s0 arguments) or a reference to an array of integers (the
\&\s-1PROBS\s0 argument).  The relative probabilities may be native integers,
\&\f(CW\*(C`Math::BigInt\*(C'\fR objects, or integer-valued \f(CW\*(C`Math::BigRat\*(C'\fR objects;
they must all be of the same type.  At least one probability value must
be positive.
.Sp
The first relative probability value (the first \s-1PROB\s0 or the first element
of \s-1PROBS\s0) is the relative probability of returning 0.  The absolute
probability of returning 0 is this value divided by the total of all
the relative probability values.  Similarly the second value controls
the probability of returning 1, and so on.
.SS "Numbers"
.IX Subsection "Numbers"
.IP "rand_fix(\s-1NBITS\s0)" 4
.IX Item "rand_fix(NBITS)"
Returns a uniformly-distributed random NBITS-bit fixed-point fraction in
the range [0, 1).  That is, the result is a randomly-chosen multiple of
2^\-NBITS, the multiplier being a random integer in the range [0, 2^NBITS).
The value is returned in the form of a native floating point number, so
\&\s-1NBITS\s0 can be at most one greater than the number of bits of significand
in the floating point format.
.Sp
With \s-1NBITS\s0 = 48 the range of output values is the same as that of the
Unix \f(CW\*(C`drand48\*(C'\fR function.
.IP "rand([\s-1LIMIT\s0])" 4
.IX Item "rand([LIMIT])"
Generates a random fixed-point fraction by \f(CW\*(C`rand_fix\*(C'\fR and then multiplies
it by \s-1LIMIT,\s0 returning the result.  \s-1LIMIT\s0 defaults to 1, and if it
is 0 then that is also treated as 1.  The length of the fixed-point
fraction is 48 bits, unless that can't be represented in the native
floating point type, in which case the longest possible fraction will
be generated instead.
.Sp
This is a drop-in replacement for \f(CW\*(C`CORE::rand\*(C'\fR: it produces exactly the
same range of output values, but using the current entropy source instead
of a sucky \s-1PRNG\s0 with linear relationships between successive outputs.
(\f(CW\*(C`CORE::rand\*(C'\fR does the type of calculation described, but using the
\&\s-1PRNG\s0 \f(CW\*(C`drand48\*(C'\fR to generate the fixed-point fraction.)  The details of
behaviour may change in the future if the behaviour of \f(CW\*(C`CORE::rand\*(C'\fR
changes, to maintain the match.
.Sp
Where the source of a module can't be readily modified, it can be made
to use this \f(CW\*(C`rand\*(C'\fR by an incantation such as
.Sp
.Vb 1
\&        *Foreign::Module::rand = \e&Data::Entropy::Algorithms::rand;
.Ve
.Sp
This must be done before the module is loaded, most likely in a \f(CW\*(C`BEGIN\*(C'\fR
block.  It is also possible to override \f(CW\*(C`CORE::rand\*(C'\fR for all modules,
by performing this similarly early:
.Sp
.Vb 1
\&        *CORE::GLOBAL::rand = \e&Data::Entropy::Algorithms::rand;
.Ve
.Sp
This function should not be used in any new code, because the kind
of output supplied by \f(CW\*(C`rand\*(C'\fR is hardly ever the right thing to use.
The \f(CW\*(C`int(rand($n))\*(C'\fR idiom to generate a random integer has non-uniform
probabilities of generating each possible value, except when \f(CW$n\fR is a
power of two.  For floating point numbers, \f(CW\*(C`rand\*(C'\fR can't generate most
representable numbers in its output range, and the output is biased
towards zero.  In new code use \f(CW\*(C`rand_int\*(C'\fR to generate integers and
\&\f(CW\*(C`rand_flt\*(C'\fR to generate floating point numbers.
.IP "rand_flt(\s-1MIN, MAX\s0)" 4
.IX Item "rand_flt(MIN, MAX)"
Selects a uniformly-distributed real number (with infinite precision)
in the range [\s-1MIN, MAX\s0] and then rounds this number to the nearest
representable floating point value, which it returns.  (Actually it is
only \fIas if\fR the function worked this way: in fact it never generates
the number with infinite precision.  It selects between the representable
floating point values with the probabilities implied by this process.)
.Sp
This can return absolutely any floating point value in the range [\s-1MIN,
MAX\s0]; both \s-1MIN\s0 and \s-1MAX\s0 themselves are possible return values.  All bits
of the floating point type are filled randomly, so the range of values
that can be returned depends on the details of the floating point format.
(See Data::Float for low-level floating point utilities.)
.Sp
The function \f(CW\*(C`die\*(C'\fRs if \s-1MIN\s0 and \s-1MAX\s0 are not both finite.  If \s-1MIN\s0 is
greater than \s-1MAX\s0 then their roles are swapped: the order of the limit
parameters actually doesn't matter.  If the limits are identical then
that value is always returned.  As a special case, if the limits are
positive zero and negative zero then a zero will be returned with a
randomly-chosen sign.
.SS "Combinatorics"
.IX Subsection "Combinatorics"
.IP "pick(\s-1ITEM ...\s0)" 4
.IX Item "pick(ITEM ...)"
Randomly selects and returns one of the ITEMs.  Each \s-1ITEM\s0 has equal
probability of being selected.
.IP "pick_r(\s-1ITEMS\s0)" 4
.IX Item "pick_r(ITEMS)"
\&\s-1ITEMS\s0 must be a reference to an array.  Randomly selects and returns
one of the elements of the array.  Each element has equal probability
of being selected.
.Sp
This is the same operation as that performed by \f(CW\*(C`pick\*(C'\fR, but using
references to avoid expensive copying of arrays.
.IP "choose(\s-1NCHOOSE, ITEM ...\s0)" 4
.IX Item "choose(NCHOOSE, ITEM ...)"
Randomly selects \s-1NCHOOSE\s0 of the ITEMs.  Each \s-1ITEM\s0 has equal probability
of being selected.  The chosen items are returned in a list in the same
order in which they appeared in the argument list.
.IP "choose_r(\s-1NCHOOSE, ITEMS\s0)" 4
.IX Item "choose_r(NCHOOSE, ITEMS)"
\&\s-1ITEMS\s0 must be a reference to an array.  Randomly selects \s-1NCHOOSE\s0 of
the elements in the array.  Each element has equal probability of being
selected.  Returns a reference to an array containing the chosen items
in the same order in which they appeared in the input array.
.Sp
This is the same operation as that performed by \f(CW\*(C`choose\*(C'\fR, but using
references to avoid expensive copying of arrays.
.IP "shuffle(\s-1ITEM ...\s0)" 4
.IX Item "shuffle(ITEM ...)"
Reorders the ITEMs randomly, and returns them in a list in random order.
Each possible order has equal probability.
.IP "shuffle_r(\s-1ITEMS\s0)" 4
.IX Item "shuffle_r(ITEMS)"
\&\s-1ITEMS\s0 must be a reference to an array.  Reorders the elements of the
array randomly.  Each possible order has equal probability.  Returns a
reference to an array containing the elements in random order.
.Sp
This is the same operation as that performed by \f(CW\*(C`shuffle\*(C'\fR, but using
references to avoid expensive copying of arrays.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Entropy,
Data::Entropy::Source
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006, 2007, 2009, 2011
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.