view release on metacpan or  search on metacpan

lib/DateTime/Event/Random.pm  view on Meta::CPAN

 # Creates a random DateTime in the future
 $dt = DateTime::Event::Random->datetime( after => DateTime->now );

 # Creates a random DateTime::Duration between 0 and 15 days
 $dur = DateTime::Event::Random->duration( days => 15 );

 # Creates a DateTime::Set of random dates 
 # with an average density of 4 months, 
 # that is, 3 events per year, with a span 
 # of 2 years
 my $dt_set = DateTime::Event::Random->new(
                  months => 4,   # events occur about 3 times a year
                  start =>  DateTime->new( year => 2003 ),
                  end =>    DateTime->new( year => 2005 ) ); 

 print "next is ", $dt_set->next( DateTime->today )->datetime, "\n";
 # output: next is 2004-02-29T22:00:51

 my @days = $dt_set->as_list;
 print join('; ', map{ $_->datetime } @days ) . "\n";
 # output: 2003-02-16T21:08:58; 2003-02-18T01:24:13; ...


=head1 DESCRIPTION

This module provides convenience methods that let you easily create
C<DateTime::Set>, C<DateTime>, or C<DateTime::Duration>
objects with random values.


=head1 USAGE

=over 4

=item * new

Creates a C<DateTime::Set> object that contains random events.

  my $random_set = DateTime::Event::Random->new;

The events occur at an average of once a day, forever.

You may give I<density> parameters to change this.
The density is specified as a duration:

  my $two_daily_set = DateTime::Event::Random->new( days => 2 );

  my $three_weekly_set = DateTime::Event::Random->new( weeks => 3 );

  my $random_set = DateTime::Event::Random->new( duration => $dur );

If I<span> parameters are given, then the set is bounded:

  my $rand = DateTime::Event::Random->new(
                 months => 4,   # events occur about 3 times a year
                 start =>  DateTime->new( year => 2003 ),
                 end =>    DateTime->new( year => 2005 ) );

Note that the random values are generated on demand, 
which means that the values may not be repeateable between iterations.
See the C<new_cached> constructor for a solution.

A C<DateTime::Set> object does not allow for the repetition of values.
Each element in a set is different.

The C<DateTime::Set> accessors (C<as_list>, C<iterator/next/previous>)
always return I<sorted> datetimes.


=item * new_cached

Creates a C<DateTime::Set> object representing the
set of random events.

    my $random_set = DateTime::Event::Random->new_cached;

If a set is created with C<new_cached>, then once an value is I<seen>,
it is cached, such that all sequences extracted from the set are equal.

Cached sets are slower and take more memory than sets generated
with the plain C<new> constructor. They should only be used if
you need unbounded sets that would be accessed many times and
when you need repeatable results.

This method accepts the same parameters as the C<new> method.


=item * datetime

Returns a random C<DateTime> object. 

    $dt = DateTime::Event::Random->datetime;

If a C<span> is specified, then the returned value will be within the span:

    $dt = DateTime::Event::Random->datetime( span => $span );

    $dt = DateTime::Event::Random->datetime( after => DateTime->now );

You can also specify C<locale> and C<time_zone> parameters,
just like in C<< DateTime->new() >>.


=item * duration

Returns a random C<DateTime::Duration> object.

    $dur = DateTime::Event::Random->duration;

If a C<duration> is specified, then the returned value will be within the
duration:

    $dur = DateTime::Event::Random->duration( duration => $dur );

    $dur = DateTime::Event::Random->duration( days => 15 );

=back

=head1 INTERNALS