Data::E...::Source(3)

💖 Data::E...::Source(3) 💖

okay bestie, so this is a User Contributed Perl Documentation page for Data::Entropy::Source — like, a whole module that hands out entropy (aka randomness) in whatever amount you want. yes even fractional bits. iconic behavior honestly ✨

---

✨ NAME ✨

Data::Entropy::Source — encapsulated source of entropy 🎀

---

🌈 SYNOPSIS 🌈

use Data::Entropy::Source;

$source = Data::Entropy::Source->new($handle, "sysread");

$c = $source->get_octet;
$str = $source->get_bits(17);
$i = $source->get_int(12345);
$i = $source->get_int(Math::BigInt->new("1000000000000"));
$j = $source->get_prob(1, 2);

look at that. five whole ways to get random stuff out of it. we love a flexible icon 💅

---

🦋 DESCRIPTION 🦋

so an object of this class is basically a wrapped source of entropy (randomness). the methods let you dispense that entropy in any quantity you need — and yes, that includes fractional bits, which is genuinely wild when you think about it. 😭

ngl, you should not normally use an entropy source object directly. it's meant to sit underneath higher-level entropy-consuming algorithms — like the ones in Data::Entropy::Algorithms. it's giving support system, not main character.

the way this works is: you construct one of these as a layer on top of a raw entropy source, because the raw source doesn't have methods to extract arbitrary amounts of entropy. raw sources are expected to dispense only entire octets at a time. the /dev/random devices on some versions of Unix are exactly that kind of source, fr fr.

the raw entropy source gets accessed through the IO::Handle interface. and it doesn't have to be IO::Handle itself supplying that interface — other classes can do it too, like Data::Entropy::RawSource::CryptCounter does. so versatile. 👑

the determinism tea ☕: if two entropy sources of this class get exactly the same raw entropy data (say, by reading from the same file), and you make exactly the same sequence of get_ method calls on both of them, they will return exactly the same values from those calls. (and heads up — calls with numerical arguments that have the same numerical value but are of different types count as the same for this purpose.) so basically you can make a run of an entropy-using algorithm completely deterministic if you want to. slay 💜

---

🎀 CONSTRUCTOR 🎀

Data::Entropy::Source->new(RAW_SOURCE, READ_STYLE)

constructs and returns an entropy source object based on the given raw source. let's break it down bestie:

• RAW_SOURCE must be an I/O handle referring to a source of entropy that can be read one octet at a time. specifically, it must support either the getc or sysread method described in IO::Handle. 📖
• READ_STYLE must be a string, either "getc" or "sysread", indicating which method should be used to read from the raw source.

and here's the cute part: no methods other than the one specified will ever be called on the raw source handle. so you do not need a full implementation of IO::Handle. lowkey a relief honestly. 🙈

which one do you use?? use "sysread" with /dev/random and its ilk, because buffering would be very wasteful of entropy and might consequently block other processes that require entropy. 😭 prefer "getc" when you're reading entropy from a regular file — and it's also the more convenient interface to implement when a non-I/O object is being used for the handle. pick wisely bestie 💅

---

⭐ METHODS ⭐

$source->get_octet

returns an octet of entropy, as a string of length one. this gives you direct access to the raw entropy source. one byte, no notes. 🍓

$source->get_bits(NBITS)

returns NBITS bits of entropy, as a string of octets. if NBITS is not a multiple of eight, then the last octet in the string has its most significant bits set to zero. math girlies rise 🧚

$source->get_int(LIMIT)

LIMIT must be a positive integer. returns a uniformly-distributed random number between zero inclusive and LIMIT exclusive. 🔥

LIMIT may be either:

• a native integer
• a Math::BigInt object
• an integer-valued Math::BigRat object

…and the returned number is of the same type. matching energy, we love to see it 💖

this method dispenses a non-integer number of bits of entropy. for example, if LIMIT is 10 then the result contains approximately 3.32 bits of entropy. the minimum non-zero amount of entropy that can be obtained is 1 bit, with LIMIT = 2. periodt.

$source->get_prob(PROB0, PROB1)

PROB0 and PROB1 must be non-negative integers, and not both zero. 🚨 each may be either a native integer, a Math::BigInt object, or an integer-valued Math::BigRat object — and the types may be mixed, no gatekeeping here.

returns either 0 or 1, with relative probabilities PROB0 and PROB1. that is:

• probability of returning 0 is PROB0/(PROB0+PROB1)
• probability of returning 1 is PROB1/(PROB0+PROB1)

this method dispenses a fraction of a bit of entropy. the maximum amount of entropy that can be obtained is 1 bit, with PROB0 = PROB1. and the more different the probabilities are, the less entropy you get. for example, if PROB0 = 1 and PROB1 = 2 then the result contains approximately 0.918 bits of entropy. so specific. so precise. ate. 💅

---

🌸 SEE ALSO 🌸

• Data::Entropy
• Data::Entropy::Algorithms
• Data::Entropy::RawSource::CryptCounter
• Data::Entropy::RawSource::Local
• IO::Handle

go read the whole friend group iykyk 🫶

---

👑 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 one's running on perl v5.42.3, dated 2026-08-02, and it's Data::E...::Source(3) from the User Contributed Perl Documentation. no cap, go generate some randomness responsibly 🌟💅✨