NAME

DateTime::Event::Random - DateTime extension for creating random datetimes.

SYNOPSIS

 use DateTime::Event::Random;

 # Creates a random DateTime
 $dt = DateTime::Event::Random->datetime;

 # 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; ...

DESCRIPTION

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

USAGE

new
Creates a "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 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 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 "new_cached" constructor for a solution.

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

The "DateTime::Set" accessors ("as_list", "iterator/next/previous") always return sorted datetimes.
new_cached
Creates a "DateTime::Set" object representing the set of random events.
```
    my $random_set = DateTime::Event::Random->new_cached;
    
```
If a set is created with "new_cached", then once an value is 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 "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 "new" method.

datetime

Returns a random "DateTime" object.

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

If a "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 "locale" and "time_zone" parameters, just like in "DateTime->new()".

duration

Returns a random "DateTime::Duration" object.

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

If a "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 );

INTERNALS

_random_init
_random_duration
These methods are called by "DateTime::Set" to generate the random datetime sequence.

You can override these methods in order to make different random distributions. The default random distribution is "uniform".

The internals API is not stable.

COOKBOOK

Make a random datetime

  use DateTime::Event::Random;

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

  print "datetime " .  $dt->datetime . "\n";

Make a random datetime, today

  use DateTime::Event::Random;

  my $dt = DateTime->today + DateTime::Event::Random->duration( days => 1 );

  print "datetime " .  $dt->datetime . "\n";

This is another way to do it. It takes care of length of day problems, such as DST changes and leap seconds:

  use DateTime::Event::Random;

  my $dt_today = DateTime->today;
  my $dt_tomorrow = $dt_today + DateTime::Duration->new( days => 1 );

  my $dt = DateTime::Event::Random->datetime( 
               start =>  $dt_today, 
               before => $dt_tomorrow );

  print "datetime " .  $dt->datetime . "\n";

Make a random sunday

  use DateTime::Event::Random;

  my $dt = DateTime::Event::Random->datetime;
  $dt->truncate( to => week );
  $dt->add( days => 6 );

  print "datetime " . $dt->datetime . "\n";
  print "weekday " .  $dt->day_of_week . "\n";

Make a random friday-13th

  use DateTime::Event::Random;
  use DateTime::Event::Recurrence;

  my $day_13 = DateTime::Event::Recurrence->monthly( days => 13 );
  my $friday = DateTime::Event::Recurrence->weekly( days => 6 ); 
  my $friday_13 = $friday->intersection( $day_13 );

  my $dt = $friday_13->next( DateTime::Event::Random->datetime );

  print "datetime " .  $dt->datetime . "\n";
  print "weekday " .   $dt->day_of_week . "\n";
  print "month day " . $dt->day . "\n";

AUTHOR

Flavio Soibelmann Glock fglock@pucrs.br

COPYRIGHT

The full text of the license can be found in the LICENSE file included with this module.