Data::E...gorithms(3)

💖 Data::Entropy::Algorithms — bestie's guide to entropy-using algorithms 💖

okay so this is a page from the User Contributed Perl Documentation section, and it's literally the manual for Data::Entropy::Algorithms. sit down, get a snack 🍓, we're doing this.

---

✨ NAME ✨

Data::Entropy::Algorithms — the basic entropy-using algorithms, aka the lil toolbox of randomness ✨

---

🌈 SYNOPSIS 🌈

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(\@items);
@chosen = choose(3, $item0, $item1, $item2, $item3, $item4);
$chosen = choose_r(3, \@items);
@shuffled = shuffle($item0, $item1, $item2, $item3, $item4);
$shuffled = shuffle_r(\@items);

---

🌸 DESCRIPTION 🌸

so basically this module is a little collection of fundamental algorithms that use entropy. all of them pull from the entropy source mechanism that's described over in Data::Entropy. that's the whole vibe 💅

---

👑 FUNCTIONS 👑

every single one of these functions uses entropy. the entropy source is not an explicit input in any case — nope, they all just use whatever the current entropy source is, the one maintained by the "Data::Entropy" module. if you wanna pick a source, use the "with_entropy_source" function in that module, or honestly just do nothing and you get the default source. main character energy either way 🫶

🎀 Fundamental entropy extraction 🎀

• rand_bits(NBITS) — gives you back NBITS bits of entropy, as a string of octets. one thing tho: if NBITS isn't a multiple of eight, then the last octet in that string has its most significant bits set to zero. no cap.
• rand_int(LIMIT) — LIMIT has to be a positive integer, periodt. returns a uniformly-distributed random integer in the range [0, LIMIT). and LIMIT can be a native integer, a "Math::BigInt" object, or an integer-valued "Math::BigRat" object — and whichever one you hand in, the number that comes back is the same type. slay.
• rand_prob(PROB ...)
• rand_prob(PROBS) — returns a random integer, but selected with non-uniform probability (yes bestie, weighted randomness, iconic). you supply the relative probabilities either as a list of non-negative integers (multiple PROB arguments) or as a reference to an array of integers (the PROBS argument). these relative probabilities can be native integers, "Math::BigInt" objects, or integer-valued "Math::BigRat" objects — but they must all be of the same type. and at least one probability value has to be positive, fr fr.

here's the tea on how it works: the first relative probability value (the first PROB, or the first element of PROBS) is the relative probability of returning 0. the absolute probability of returning 0 is that value divided by the total of all the relative probability values. and then it just keeps going — the second value controls the probability of returning 1, and so on. simple as that. 💖

🦋 Numbers 🦋

• rand_fix(NBITS) — returns a uniformly-distributed random NBITS-bit fixed-point fraction in the range [0, 1). like, the result is a randomly-chosen multiple of 2^-NBITS, and the multiplier is a random integer in the range [0, 2^NBITS). it comes back to you in the form of a native floating point number, which means NBITS can be at most one greater than the number of bits of significand in the floating point format.

and with NBITS = 48, the range of output values is literally the same as that of the Unix "drand48" function. cute!

• rand([LIMIT]) — generates a random fixed-point fraction by way of "rand_fix" and then multiplies it by LIMIT, returning the result. LIMIT defaults to 1, and if it's 0 then that also gets treated as 1 (we don't do zero around here). 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 gets generated instead. adaptable queen 💅

this one is a drop-in replacement for "CORE::rand": it produces exactly the same range of output values, but it uses the current entropy source instead of a sucky PRNG with linear relationships between successive outputs. ("CORE::rand" does the type of calculation described, but using the PRNG "drand48" to generate the fixed-point fraction.) and heads up — the details of behaviour may change in the future if the behaviour of "CORE::rand" changes, to maintain the match. keeping it consistent, iykyk.

where the source of a module can't be readily modified, you can make it use this "rand" by an incantation such as:

*Foreign::Module::rand = \&Data::Entropy::Algorithms::rand;

this must be done before the module is loaded — most likely in a "BEGIN" block. it's also possible to override "CORE::rand" for all modules, by performing this similarly early:

*CORE::GLOBAL::rand = \&Data::Entropy::Algorithms::rand;

🚨 okay bestie, important: this function should not be used in any new code, because the kind of output supplied by "rand" is hardly ever the right thing to use. the int(rand($n)) idiom to generate a random integer has non-uniform probabilities of generating each possible value, except when $n is a power of two. and for floating point numbers, "rand" can't generate most representable numbers in its output range, and the output is biased towards zero. in new code use "rand_int" to generate integers and "rand_flt" to generate floating point numbers. periodt. 💀

• rand_flt(MIN, MAX) — selects a uniformly-distributed real number (with infinite precision, fancy) in the range [MIN, MAX] and then rounds that number to the nearest representable floating point value, which it returns. (okay so actually it's only as if 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. the illusion is flawless tho ✨)

this can return absolutely any floating point value in the range [MIN, MAX] — both MIN and MAX 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.)

it "die"s if MIN and MAX are not both finite 😭. if MIN is greater than MAX then their roles are swapped — the order of the limit parameters actually doesn't matter, we're flexible. if the limits are identical then that value is always returned. and as a special case: if the limits are positive zero and negative zero, then a zero will be returned with a randomly-chosen sign. iconic behaviour tbh.

💜 Combinatorics 💜

• pick(ITEM ...) — randomly selects and returns one of the ITEMs. each ITEM has equal probability of being selected. no favourites here 🫶
• pick_r(ITEMS) — ITEMS must be a reference to an array. randomly selects and returns one of the elements of the array, and each element has equal probability of being selected.

this is the same operation as that performed by "pick", but using references to avoid expensive copying of arrays. efficiency slay ✨

• choose(NCHOOSE, ITEM ...) — randomly selects NCHOOSE of the ITEMs. each ITEM 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.
• choose_r(NCHOOSE, ITEMS) — ITEMS must be a reference to an array. randomly selects NCHOOSE of the elements in the array, each element with 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.

this is the same operation as that performed by "choose", but using references to avoid expensive copying of arrays. same energy, less copying 💅

• shuffle(ITEM ...) — reorders the ITEMs randomly and returns them in a list in random order. every possible order has equal probability. go off, chaos 🌀
• shuffle_r(ITEMS) — ITEMS must be a reference to an array. reorders the elements of the array randomly, every possible order with equal probability. returns a reference to an array containing the elements in random order.

this is the same operation as that performed by "shuffle", but using references to avoid expensive copying of arrays.

---

💫 SEE ALSO 💫

• Data::Entropy
• Data::Entropy::Source

---

🌟 AUTHOR 🌟

Andrew Main (Zefram) <zefram@fysh.org>

Maintained by Robert Rothenberg <perl@rhizomnic.com>

---

🎀 COPYRIGHT 🎀

Copyright (C) 2006, 2007, 2009, 2011, 2025-2026 Andrew Main (Zefram) <zefram@fysh.org>

---

⭐ LICENSE ⭐

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie 🫶 this was Data::E...gorithms(3) from perl v5.42.3, dated 2026-08-02, no cap. go be random responsibly 💖✨