Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Event::RandoUser Contributed Perl DocumentDateTime::Event::Random(3)

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

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

       o   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()".

       o   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
       o   _random_init

       o   _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
       o   Make	a random datetime

	     use DateTime::Event::Random;

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

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

       o   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";

       o   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";

       o   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
       Copyright (c) 2004 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	and DateTime::Duration - date and time.

       DateTime::Set - "sets"

perl v5.32.1			  2004-03-17	    DateTime::Event::Random(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | INTERNALS | COOKBOOK | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Event::Random&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help