The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Venus-4.15
River stage two • 3 direct dependents • 56 total dependents
/ Venus::Random

NAME

Venus::Random - Random Class

ABSTRACT

Random Class for Perl 5

SYNOPSIS

package main;

use Venus::Random;

my $random = Venus::Random->new(42);

# my $bit = $random->bit;

# 1

DESCRIPTION

This package provides an object-oriented interface for Perl's pseudo-random number generator (or PRNG) which produces a deterministic sequence of bits which approximate true randomness.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Accessible

Venus::Role::Buildable

Venus::Role::Valuable

METHODS

This package provides the following methods:

bit

bit() (number)

The bit method returns a 1 or 0 value, randomly.

Since 1.11

bit example 1
# given: synopsis

package main;

my $bit = $random->bit;

# 0

# $bit = $random->bit;

# 1

boolean

boolean() (boolean)

The boolean method returns a true or false value, randomly.

Since 1.11

boolean example 1
# given: synopsis

package main;

my $boolean = $random->boolean;

# 0

# $boolean = $random->boolean;

# 1

byte

byte() (string)

The byte method returns random byte characters, randomly.

Since 1.11

byte example 1
# given: synopsis

package main;

my $byte = $random->byte;

# "\xBE"

# $byte = $random->byte;

# "W"

character

character() (string)

The character method returns a random character, which is either a "digit", "letter", or "symbol" value.

Since 1.11

character example 1
# given: synopsis

package main;

my $character = $random->character;

# ")"

# $character = $random->character;

# 4

collect

collect(number $times, string | coderef $code, any @args) (number | string)

The collect method dispatches to the specified method or coderef, repeatedly based on the number of $times specified, and returns the random concatenated results from each dispatched call. By default, if no arguments are provided, this method dispatches to "digit".

Since 1.11

collect example 1
# given: synopsis

package main;

my $collect = $random->collect;

# 7

# $collect = $random->collect;

# 3
collect example 2
# given: synopsis

package main;

my $collect = $random->collect(2);

# 73

# $collect = $random->collect(2);

# 14
collect example 3
# given: synopsis

package main;

my $collect = $random->collect(5, "letter");

# "iKWMv"

# $collect = $random->collect(5, "letter");

# "Papmm"
collect example 4
# given: synopsis

package main;

my $collect = $random->collect(10, "character");

# ")48R+a}[Lb"

# $collect = $random->collect(10, "character");

# "?&0725^,0w"

digit

digit() (number)

The digit method returns a random digit between 0 and 9.

Since 1.11

digit example 1
# given: synopsis

package main;

my $digit = $random->digit;

# 7

# $digit = $random->digit;

# 3

float

float(number $place, number $from, number $upto) (number)

The float method returns a random float.

Since 1.11

float example 1
# given: synopsis

package main;

my $float = $random->float;

# 1447361.5

# $float = $random->float;

# "0.0000"
float example 2
# given: synopsis

package main;

my $float = $random->float(2);

# 380690.82

# $float = $random->float(2);

# 694.57
float example 3
# given: synopsis

package main;

my $float = $random->float(2, 1, 5);

# 3.98

# $float = $random->float(2, 1, 5);

# 2.37
float example 4
# given: synopsis

package main;

my $float = $random->float(3, 1, 2);

# 1.745

# $float = $random->float(3, 1, 2);

# 1.343

letter

letter() (string)

The letter method returns a random letter, which is either an "uppercased" or "lowercased" value.

Since 1.11

letter example 1
# given: synopsis

package main;

my $letter = $random->letter;

# "i"

# $letter = $random->letter;

# "K"

lowercased

lowercased() (string)

The lowercased method returns a random lowercased letter.

Since 1.11

lowercased example 1
# given: synopsis

package main;

my $lowercased = $random->lowercased;

# "t"

# $lowercased = $random->lowercased;

# "i"

nonzero

nonzero(string | coderef $code, any @args) (number | string)

The nonzero method dispatches to the specified method or coderef and returns the random value ensuring that it's never zero, not even a percentage of zero. By default, if no arguments are provided, this method dispatches to "digit".

Since 1.11

nonzero example 1
# given: synopsis

package main;

my $nonzero = $random->nonzero;

# 7

# $nonzero = $random->nonzero;

# 3
nonzero example 2
# given: synopsis

package main;

my $nonzero = $random->nonzero("pick");

# 1.74452500006101

# $nonzero = $random->nonzero("pick");

# 1.34270147871891
nonzero example 3
# given: synopsis

package main;

my $nonzero = $random->nonzero("number");

# 3427014

# $nonzero = $random->nonzero("number");

# 3
nonzero example 4
# given: synopsis

package main;

my $nonzero = $random->nonzero("number", 0, 10);

# 8

# $nonzero = $random->nonzero("number", 0, 10);

# 3

number

number(number $from, number $upto) (number)

The number method returns a random number within the range provided. If no arguments are provided, the range is from 0 to 2147483647. If only the first argument is provided, it's treated as the desired length of the number.

Since 1.11

number example 1
# given: synopsis

package main;

my $number = $random->number;

# 3427014

# $number = $random->number;

# 3
number example 2
# given: synopsis

package main;

my $number = $random->number(5, 50);

# 39

# $number = $random->number(5, 50);

# 20
number example 3
# given: synopsis

package main;

my $number = $random->number(100, 20);

# 42

# $number = $random->number(100, 20);

# 73
number example 4
# given: synopsis

package main;

my $number = $random->number(5);

# 74451

# $number = $random->number(5);

# 34269

pick

pick(Num $data) (Num)

The pick method is the random number generator and returns a random number. By default, calling this method is equivalent to call "rand" in perlfunc. This method can be overridden in a subclass to provide a custom generator, e.g. a more cyptographically secure generator.

Since 1.23

pick example 1
# given: synopsis

package main;

my $pick = $random->pick;

# 0.744525000061007

# $pick = $random->pick;

# 0.342701478718908
pick example 2
# given: synopsis

package main;

my $pick = $random->pick(100);

# 74.4525000061007

# $pick = $random->pick(100);

# 34.2701478718908
pick example 3
# given: synopsis

package main;

my $pick = $random->pick(2);

# 1.48905000012201

# $pick = $random->pick(2);

# 0.685402957437816

range

range(string $from, string $to) (number)

The range method returns a random number within the range provided. If no arguments are provided, the range is from 0 to 2147483647.

Since 1.11

range example 1
# given: synopsis

package main;

my $range = $random->range(1, 10);

# 8

# $range = $random->range(1, 10);

# 4
range example 2
# given: synopsis

package main;

my $range = $random->range(10, 1);

# 5

# $range = $random->range(10, 1);

# 8
range example 3
# given: synopsis

package main;

my $range = $random->range(0, 60);

# 45

# $range = $random->range(0, 60);

# 20
range example 4
# given: synopsis

package main;

my $range = $random->range(-5, -1);

# -2

# $range = $random->range(-5, -1);

# -4

repeat

repeat(number $times, string | coderef $code, any @args) (number | string)

The repeat method dispatches to the specified method or coderef, repeatedly based on the number of $times specified, and returns the random results from each dispatched call. In list context, the results from each call is returned as a list, in scalar context the results are concatenated.

Since 1.11

repeat example 1
# given: synopsis

package main;

my @repeat = $random->repeat(2);

# (7, 3)

# @repeat = $random->repeat(2);

# (1, 4)
repeat example 2
# given: synopsis

package main;

my @repeat = $random->repeat(2, "float");

# (1447361.5, "0.0000")

# @repeat = $random->repeat(2, "float");

# ("482092.1040", 1555.7410393)
repeat example 3
# given: synopsis

package main;

my @repeat = $random->repeat(2, "character");

# (")", 4)

# @repeat = $random->repeat(2, "character");

# (8, "R")

reseed

reseed(string $seed) (Venus::Random)

The reseed method sets the "srand" in perlfunc (i.e. the PRNG seed) to the value provided, or the default value used on instanstiation when no seed is passed to the constructor. This method returns the object that invoked it.

Since 1.11

reseed example 1
# given: synopsis

package main;

my $reseed = $random->reseed;

# bless({value => ...}, "Venus::Random")

# my $bit = $random->bit;

# 0
reseed example 2
# given: synopsis

package main;

my $reseed = $random->reseed(42);

# bless({value => 42}, "Venus::Random")

# my $bit = $random->bit;

# 0

reset

reset() (Venus::Random)

The reset method sets the "srand" in perlfunc (i.e. the PRNG seed) to the default value used on instanstiation when no seed is passed to the constructor. This method returns the object that invoked it.

Since 1.11

reset example 1
# given: synopsis

package main;

my $reset = $random->reset;

# bless({value => ...}, "Venus::Random")

restore

restore() (Venus::Random)

The restore method sets the "srand" in perlfunc (i.e. the PRNG seed) to the original value used by "rand" in perlfunc. This method returns the object that invoked it.

Since 1.11

restore example 1
# given: synopsis

package main;

my $restore = $random->restore;

# bless({value => ...}, "Venus::Random")

select

select(arrayref | hashref $data) (any)

The select method returns a random value from the "hashref" or "arrayref" provided.

Since 1.11

select example 1
# given: synopsis

package main;

my $select = $random->select(["a".."d"]);

# "c"

# $select = $random->select(["a".."d"]);

# "b"
select example 2
# given: synopsis

package main;

my $select = $random->select({"a".."h"});

# "f"

# $select = $random->select({"a".."h"});

# "d"

symbol

symbol() (string)

The symbol method returns a random symbol.

Since 1.11

symbol example 1
# given: synopsis

package main;

my $symbol = $random->symbol;

# "'"

# $symbol = $random->symbol;

# ")"

uppercased

uppercased() (string)

The uppercased method returns a random uppercased letter.

Since 1.11

uppercased example 1
# given: synopsis

package main;

my $uppercased = $random->uppercased;

# "T"

# $uppercased = $random->uppercased;

# "I"

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.