File Coverage

blib/lib/Math/Random/Secure.pm

Criterion	Covered	Total	%
statement	36	37	97.3
branch	11	12	91.6
condition			n/a
subroutine	9	9	100.0
pod	3	3	100.0
total	59	61	96.7

package Math::Random::Secure;
$Math::Random::Secure::VERSION = '0.08';
# ABSTRACT: Cryptographically-secure, cross-platform replacement for rand()

use strict;
use 5.008;
use base qw(Exporter);
use Math::Random::Secure::RNG;

# ISAAC, a 32-bit generator, should only be capable of generating numbers
# between 0 and 2^32 - 1. We want _to_float to generate numbers possibly
# including 0, but always less than 1.0. Dividing the integer produced
# by irand() by this number should do that exactly.
use constant DIVIDE_BY => 2**32;

our $RNG;

our @EXPORT_OK = qw(rand srand irand);

sub rand (;$) {
    my ($limit) = @_;
    my $int = irand();
    return _to_float($int, $limit);
}

sub irand (;$) {
    my ($limit) = @_;
    Math::Random::Secure::srand() if !defined $RNG;
    my $int = $RNG->irand();
    if (defined $limit) {
        # We can't just use the mod operator because it will bias
        # our output. Search for "modulo bias" on the Internet for
        # details. This is slower than mod(), but does not have a bias,
        # as demonstrated by our uniform.t test.
        return int(_to_float($int, $limit));
    }
    return $int;
}

sub srand (;$) {
    my ($value) = @_;
    if (defined $RNG) {
        if (defined $value) {
            $RNG->seed($value);
        }
        else {
            $RNG->clear_seed;
        }
        $RNG->clear_rng;
    }
    else {
        my %args;
        if (defined $value) {
            $args{seed} = $value;
        }
        $RNG = Math::Random::Secure::RNG->new(%args);
    }
    # This makes srand return the seed and also makes sure that we
    # get the seed right now, if no $value was passed.
    return $RNG->seed;
}

sub _to_float {
    my ($integer, $limit) = @_;
    $limit = 1 if !$limit;
    return ($integer / DIVIDE_BY) * $limit;
}

__PACKAGE__

__END__