/ 
Math-BigInt-Random-OO-0.01
River stage zero No dependents
/ Math::BigInt::Random::OO

NAME

Math::BigInt::Random::OO - generate uniformly distributed Math::BigInt objects

SYNOPSIS

use Math::BigInt::Random::OO;

# Random numbers between 1e20 and 2e30:

my $gen = Math::BigInt::Random::OO -> new(min => "1e20",
                                          min => "2e30");
$x = $gen -> generate();      # one number
$x = $gen -> generate(1);     # ditto
@x = $gen -> generate(100);   # 100 numbers

# Random numbers with size fitting 20 hexadecimal digits:

my $gen = Math::BigInt::Random::OO -> new(length => 20,
                                          base => 16);
@x = $gen -> generate(100);

ABSTRACT

Math::BigInt::Random::OO is a module for generating arbitrarily large random integers from a discrete, uniform distribution. The numbers are returned as Math::BigInt objects.

DESCRIPTION

Math::BigInt::Random::OO is a module for generating arbitrarily large random integers from a discrete, uniform distribution. The numbers are returned as Math::BigInt objects.

CONSTRUCTORS

CLASS -> new ( ... )

Returns a new Math::BigInt::Random::OO random number generator object. The arguments are given in the "hash style", as shown in the following example which constructs a generator for random numbers in the range from -2 to 3, inclusive.

my $gen = Math::BigInt::Random::OO -> new(min => -2, max => 3);

The following parameters are recognized.

min => NUM

Specifies the minimum possible output value, i.e., the lower bound. If ‘max’ is given, but ‘min’ is not, then ‘min’ is set to zero.

max => NUM

Specifies the maximum possible output value, i.e., the upper bound. If ‘max’ is given, but ‘min’ is not, then ‘max’ must be non-negative.

length => NUM

Specifies the length of the output value, i.e., the number of digits. Use this option to ensure that all random numbers have the same number of digits. If the base is not given explicitly with the ‘base’ option, then a base of 10 is used. The following two constructors are equivalent

Math::BigInt::Random::OO -> new(length => $n, base => $b);

$min = Math::BigInt -> new($b) -> bpow($n - 1);
$max = Math::BigInt -> new($b) -> bpow($n) -> bsub(1));
Math::BigInt::Random::OO -> new(min => $min, max => $max);

For instance, if the length is 4 and the base is 10, the random numbers will be in the range from 1000 to 9999 (decimal), inclusive. If the length is 3 and the base is 16, the random numbers will be in the range from 256 to 4095 (decimal).

This option is ignored if the ‘max’ option is present.

base => NUM

Sets the base to be used with the ‘length’ option. See also the description for the ‘length’ option.

length_bin => NUM

This option is only compatibility with Math::BigInt::Random. The following two cases are equivalent

$cls -> new(length_bin => $n);
$cls -> new(length => $n, base => 2);
length_hex => NUM

This option is only compatibility with Math::BigInt::Random. The following two cases are equivalent

$cls -> new(length_hex => $n);
$cls -> new(length => $n, base => 16);
OBJECT -> generate ( COUNT )
OBJECT -> generate ( )

Generates the given number of random numbers, or one number, if no input argument is given.

# Generate ten random numbers:

my @num = $gen -> generate(10);

TODO

  • Add a way to change the core uniform random number generator. Currently, CORE::rand() is used, but it would be nice to be able to switch to, e.g., Math::Random::random_uniform_integer().

  • Add functionality similar to the ‘use_internet’ parameter argument in Math::BigInt::Rando::random_bigint(). This could be implemented using, e.g., Net::Random.

  • Add more tests.

NOTES

How Math::BigInt::Random::OO works

The generate() method generates a big random integer $X in the range $Xmin ≤ $X ≤ $Xmax by first generating a random integer $U in the range 0 ≤ $U ≤ $R < 2**$N, where $R is the range $Xmax - $Xmin, and $N is the smallest integer so that $R < 2**$N. If $U > $R, then $U is discarded and a new $U is generated until $U ≤ $R.

A random integer $U in the range 0 ≤ $U < 2**$N is generated by combining smaller random integers $V in the range 0 ≤ $V < 2**$M, where $M ≤ $N. The smaller random integers are generated with Perl’s own routine for generating uniformly distributed integers, CORE::rand(). Care is taken so that $M is never larger than RANDBITS.

You can see the number of RANDBITS in your Perl with

$ perl -MConfig -wle 'print $Config{randbits}'

or

$ perl -V:randbits

Problems with Math::BigInt::Random

I wrote this module since Math::BigInt::Random v0.04 is buggy, and in many cases slower. The bugs in Math::BigInt::Random v0.04 is

  • When the range (the maximum value minus the minimum value) is smaller than 0xfffff hexadecimal, which is 1048575 decimal, then the maximum value will never be returned.

  • When Perl has been compiled with a number of RANDBITS less than 20, certain values will never occur.

  • When the range is not a power of two, certain values are more likely to occur than others.

The core of this two last problems is the use of int(rand(X)), which only returns uniformly distributed numbers when X is a power of two no larger than RANDBITS.

In addition, the function Math::BigInt::Random::random_bigint() generates only one random integer at a time, and in doing so, there is some overhead. In Math::BigInt::Random::OO, this overhead is placed in the new() constructor, so it is only done once, independently of how many random numbers are generated by the generator() method.

CAVEATS

  • Some versions of Perl are compiled with the wrong number of RANDBITS. This module has way to detect if this is the case.

  • Some versions of CORE::rand() behave poorly. For intance, in some implementations

    rand(1 << $Config{randbits}) % 2

    alternates between 0 and 1 deterministically.

BUGS

There are currently no known bugs.

Please report any bugs or feature requests to bug-math::bigint::random::oo at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-BigInt-Random-OO. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Math::BigInt::Random::OO

You can also look for information at:

SEE ALSO

Math::BigInt::Random(3), Math::Random(3), Net::Random(3).

AUTHOR

Peter John Acklam, <pjacklam@cpan.org>

COPYRIGHT & LICENSE

Copyright 2010 by Peter John Acklam <pjacklam@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 89:

Non-ASCII character seen before =encoding in '‘max’'. Assuming UTF-8