view release on metacpan or  search on metacpan

lib/Data/Rand.pm  view on Meta::CPAN

In array context it returns a list the length of number of parts you want where each item is from the array of parts.

Takes 0 to 3 arguments:

=over

=item 1) length or number of random parts (default if not given or invalid is 32)

=item 2) array ref of parts (default if not given or invalid is 0 .. 9 and upper and lower case a-z)

=item 3) hashref of behavioral options (this one can also be passed as the only argument or the second argument so long as its the *last* argument)

keys and values are described below, unless otherwise noted options are booleans which default to false

=over

=item * 'use_unique_list' 

Make sure array of parts is unique. If you're passing the same list more than once and you are doing this each time it'd be more efficient to uniq() the list once and pass that to the function instead of using this.

=item * 'do_not_repeat_index' 

Do not use any index of the array of parts more than once.

Caveat: if the length is longer than the list of items then the length is silently adjusted to the length of the list.

    my $length = 10;
    my @random = rand_data( $length, @deck_of_cards, { 'do_not_repeat_index' => 1 } );
    # @random has 10 items

    my $length = 53;
    my @random = rand_data( $length, @deck_of_cards, { 'do_not_repeat_index' => 1 } );
    # @random has 52 items

Caveat: This is not a uniq() functionality on the list of items, this is "no repeat" based on index. So:

    rand_data(3, [qw(dan dan dan)]);

is valid (if not very useful) because it won't use index 0, 1, or 2 more than once

This is probably what you'd want:

    rand_data($n, [ uniq @people ] ); # could still contain duplicates in results by using the same index more than once

or even:

    rand_data($n, \@people, { 'do_not_repeat_index' => 1, 'use_unique_list' => 1 } ); # definitely no duplicates since you uniq()ed the list *and* told it to only use each index at most once

Caveat: This also increases calculation time since it has to see if 
a randomly chosen index has already been used and if so try again. 

=item * 'get_random_index'

This should be a code ref that accepts one argument, the number of items we have to choose from, and returns an index chosen at random (however you choose to define "random")

    sub {
        my ($length) = @_;
        return Crypt::Random::makerandom_itv( 'Lower' => 0, 'Upper' => $length, ...); 
    }

Note: The above example (w/ Strong => 0 (IE read() is not being blocked on /dev/random)) benchmarked appx 570 times as slow as the default L<rand>() based solution but its much more truly random.

=back

=back

=head2 rand_data_string()

Same args as rand_data(). The difference is that it always returns a string regardless of context.

    my $rand_str = rand_data_string( @rand_args ); # $rand_str contains the random string.
    my @stuff    = rand_data_string( @rand_args ); # $stuff[0] contains the random string.

=head2 rand_data_array()

Same args as rand_data(). The difference is that it always returns an array regardless of context.

    my @rand_data = rand_data_array( @rand_args ); # @rand_data contains the random items
    my $rand_data = rand_data_array( @rand_args ); # $rand_data is an array ref to the list of random items

=head2 seed_calc_with()

This is a simple shortcut function you can use to call L<srand>() for you with a pre-done calculation as outlined below. If this does not do what you like use L<srand>() directly.

It brings in L<Time::HiRes> for you if needed and then calls L<srand>() like so:

    srand($hires_time, $hires_micro_seconds, $$, 'YOUR ARGUEMENT HERE' || rand( 999_999_999_999_999));

You don't have to call it of course but here are some examples if you choose to:

    seed_calc_with();                                  # same as seed_calc_with( rand( 999_999_999_999_999 ) );
    seed_calc_with( rand( 999_999_999_999_999 ) );     # same as seed_calc_with();
    seed_calc_with( unpack '%L*', `ps axww | gzip` );
    seed_calc_with( Math::TrulyRandom::truly_random_value() );
    seed_calc_with( Crypt::Random::makerandom(...) ); 

Its not exportable on purpose to discourage blindly using it since calling L<srand>() improperly can result in L<rand>()'s result being less random.

See L<srand> and L<rand> for more information.

=head1 DIAGNOSTICS

Throws no warnings or errors of its own.

=head1 CONFIGURATION AND ENVIRONMENT
  
Data::Rand requires no configuration files or environment variables.

=head1 DEPENDENCIES

L</seed_calc_with>() brings in L<Time::HiRes>

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to