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

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