NAME

       Math::Random::MT::Auto::Range - Range-valued PRNGs

SYNOPSIS

           use strict;
           use warnings;
           use Math::Random::MT::Auto::Range;

           # Integer random number range
           my $die = Math::Random::MT::Auto::Range->new(LO => 1, HI => 6);
           my $roll = $die->rrand();

           # Floating-point random number range
           my $compass = Math::Random::MT::Auto::Range->new(LO => 0, HI => 360,
                                                            TYPE => 'DOUBLE');
           my $course = $compass->rrand();

DESCRIPTION

       This module creates range-valued pseudorandom number generators (PRNGs) that return random values between
       two specified limits.

       While useful in itself, the primary purpose of this module is to provide an example of how to create
       subclasses of Math::Random::MT::Auto within Object::InsideOut's inside-out object model.

MODULE DECLARATION

       Add the following to the top of our application code:

           use strict;
           use warnings;
           use Math::Random::MT::Auto::Range;

       This module is strictly OO, and does not export any functions or symbols.

METHODS

       Math::Random::MT::Auto::Range->new
           Creates a new range-valued PRNG.

               my $prng = Math::Random::MT::Auto::Range->new( %options );

           Available options are:

           'LOW' => $num
           'HIGH' => $num
               Sets  the  limits  over  which  the  values  return  by the PRNG will range.  These arguments are
               mandatory, and "LOW" must not be equal to "HIGH".

               If the "TYPE" for the PRNG is "INTEGER", then the range will be "LOW" to "HIGH" inclusive  (i.e.,
               [LOW, HIGH]).  If "DOUBLE", then "LOW" inclusive to "HIGH" exclusive (i.e., [LOW, HIGH)).

               "LO" and "HI" can be used as synonyms for "LOW" and "HIGH", respectively.

           'TYPE' => 'INTEGER'
           'TYPE' => 'DOUBLE'
               Sets the type for the values returned from the PRNG.  If "TYPE" is not specified, it will default
               to "INTEGER" if both "LOW" and "HIGH" are integers.

           The  options  above  are  also  supported  using lowercase and mixed-case (e.g., 'low', 'hi', 'Type',
           etc.).

           Additionally, objects created with this package  can  take  any  of  the  options  supported  by  the
           Math::Random::MT::Auto class, namely, "STATE", "SEED" and "STATE".

       $obj->new
           Creates a new PRNG in the same manner as "Math::Random::MT::Auto::Range->new".

               my $prng2 = $prng1->new( %options );

       In  addition  to  the  methods describe below, the objects created by this package inherit all the object
       methods provided by the Math::Random::MT::Auto class, including the "-"clone()> method.

       $obj->rrand
           Returns a random number of the configured type within the configured range.

               my $rand = $prng->rrand();

           If the "TYPE" for the PRNG is "INTEGER", then the range will be  "LOW"  to  "HIGH"  inclusive  (i.e.,
           [LOW, HIGH]).  If "DOUBLE", then "LOW" inclusive to "HIGH" exclusive (i.e., [LOW, HIGH)).

       $obj->set_range_type
           Sets the numeric type for the random numbers returned by the PRNG.

               $prng->set_range_type('INTEGER');
                 # or
               $prng->set_range_type('DOUBLE');

       $obj->get_range_type
           Returns the numeric type ('INTEGER' or 'DOUBLE') for the random numbers returned by the PRNG.

               my $type = $prng->get_range_type();

       $obj->set_range
           Sets the limits for the PRNG's return value range.

               $prng->set_range($lo, $hi);

           $lo must not be equal to $hi.

       $obj->get_range
           Returns a list of the PRNG's range limits.

               my ($lo, $hi) = $prng->get_range();

INSIDE-OUT OBJECTS

       Capabilities  provided  by  Object::InsideOut are supported by this modules.  See "INSIDE-OUT OBJECTS" in
       Math::Random::MT::Auto for more information.

   Coercion
       Object coercion is supported in the same manner as documented in See "Coercion" in Math::Random::MT::Auto
       except that the underlying random number method is "->rrand()".

DIAGNOSTICS

       •   Missing parameter: LOW

       •   Missing parameter: HIGH

           The LOW and HIGH values for the range must be specified to ->new().

       •   Arg to ->set_range_type() must be 'INTEGER' or 'DOUBLE'

           Self explanatory.

       •   ->range() requires two numeric args

           Self explanatory.

       •   Invalid arguments: LOW and HIGH are equal

           You cannot specify a range of zero width.

       This module will reverse the range limits if they are specified in the wrong order (i.e., it  makes  sure
       that "LOW < HIGH").

SEE ALSO

       Math::Random::MT::Auto

       Object::InsideOut

AUTHOR

       Jerry D. Hedden, <jdhedden AT cpan DOT org>

COPYRIGHT AND LICENSE

       Copyright 2005 - 2009 Jerry D. Hedden. All rights reserved.

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

perl v5.40.0                                       2024-10-20                 Math::Random::MT::Auto::Range(3pm)