/ 
Math-Rand48-Cursor-0.001
/ Math::Rand48::Cursor

NAME

Math::Rand48::Cursor - Move forward and backward in the drand48/rand() sequence

SYNOPSIS

use Math::Rand48::Cursor;

# Recover the generator state from one observed rand() output:
my $obs = rand;
my $rng = Math::Rand48::Cursor->from_rand($obs);

$rng->rand;                 # == $obs
$rng->forward->rand;        # the next rand() output
$rng->backward->rand;       # the previous one

$rng->seek(1_000_000);      # jump a million steps ahead
$rng->seek(-1_000_000);     # and back

DESCRIPTION

Perl's rand is drand48(3), a 48-bit linear congruential generator. Its steps can be run in reverse, so a single rand() output is enough to recover the full internal state. From there you can jump to any point in the sequence.

METHODS

new

my $rng = Math::Rand48::Cursor->new( state => $x );

Construct a cursor at an explicit 48-bit state (integer, string, or Math::BigInt). Defaults to 0.

from_rand

my $rng = Math::Rand48::Cursor->from_rand($observed);

Construct a cursor at the state that produced a single observed rand() output.

from_seed48

my $rng   = Math::Rand48::Cursor->from_seed48($seed);
my $first = $rng->forward->rand;    # the first rand() after srand($seed)

Construct a cursor at the state set by srand($seed), before the first output.

Seed handling

$seed follows Perl's srand coercion rules, so from_seed48 inverts srand:

  • Fractional seeds truncate toward zero (3.7 becomes 3).

  • Negative seeds use their absolute value (-1 seeds like 1), following Perl rather than libc's srand48.

  • Only the low 32 bits matter, so seeds >= 2**32 wrap.

  • NaN and Inf are rejected with croak.

state

The current 48-bit state as a Math::BigInt.

rand

The float rand() would return for the current state.

seek

$rng->seek($n);

Move $n steps along the sequence; negative $n seeks backward. Mutates the cursor and returns it (chainable).

forward / backward

Shorthand for seek(1) and seek(-1).

AUTHOR

Stig Palmquist <stig@stig.io>

LICENSE

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