NAME

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

SYNOPSIS

 use DateTime::Event::Random;

 # 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 $rand = DateTime::Event::Random->new(
     months => 4,
     start => DateTime->new( year => 2003 ),
     end =>   DateTime->new( year => 2005 ),
 ); 

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

 my $count = $rand->count;
 print "days $count \n";
 # output: days 8  -- should be a number near 6

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


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


 # Create a DateTime::Duration
 $dur = DateTime::Event::Random->duration( days => 15 );

DESCRIPTION

This module provides convenience methods that let you easily create DateTime::Set objects with random datetimes.

It also provides functions for building random DateTime and DateTime::Duration objects.

USAGE

• new

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

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

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

  You may give density parameters to change this:

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

  If span parameters are given, then the set is limited to the span:

   my $rand = DateTime::Event::Random->new(
       months => 4,
       start => DateTime->new( year => 2003 ),
       end =>   DateTime->new( year => 2005 ),
   );

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

• 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.

• 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 );

• 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 );

NOTES

The DateTime::Set module does not allow for repetition of values. That is, a function like next($dt) will always return a value bigger than $dt. Each element in a set is different.

Although the datetime values in the DateTime::Set are random, the accessors (as_list, iterator/next/previous) always return sorted datetimes.

The set functions calculate all intervals in seconds, which may give a 32-bit integer overflow if you ask for a density less than about "1 occurence in each 30 years" - which is about a billion seconds. This may change in a next version.

COOKBOOK

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 $friday = DateTime::Event::Recurrence->monthly( days => 13 );
  my $day_13 = 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";

Make a random datetime, today

  use DateTime::Event::Random;

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

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

AUTHOR

Flavio Soibelmann Glock fglock@pucrs.br

COPYRIGHT

Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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

SEE ALSO

datetime@perl.org mailing list

DateTime Web page at http://datetime.perl.org/

DateTime - date and time :)

DateTime::Set - for recurrence-set accessors docs.

cpanm DateTime::Event::Random

perl -MCPAN -e shell
install DateTime::Event::Random