NAME
Time::R  Handle recurrences.
VERSION
version 0.024
SYNOPSIS
use Time::C;
use Time::R;
my $start = Time::C>new(2016,1,31);
my $r = Time::R>new($start, months => 1);
# "20160229T00:00:00Z"
my $first = $r>next();
# "20160331T00:00:00Z
my $second = $r>next();
# resets $r>next()
$r>reset();
# 20161031T00:00:00Z" (depending on current time)
my $upcoming = $r>upcoming();
# "20160930T00:00:00Z" (depending on current time)
my $latest = $r>latest();
# ("20160930T00:00:00Z", "20161031T00:00:00Z", "20161130T00:00:00Z",
# "20161231T00:00:00Z")
my @dates = $r>until(Time::C>new(2017,1,1));
# "20170131T00:00:00Z"
my $next = $r>next();
# print out the first thursday of every month until January 2017
my $m = Time::R>new(Time::C>new(2016), months => 1, end => Time::C>new(2017));
while (my $n = $m>next()) {
$n>day++ while $n>day_of_week != 4;
print $n>strftime('%A %d %B %Y') . "\n"; #ex: Thursday 4 February 2016
}
DESCRIPTION
Convenient ways of handling recurrences.
CONSTRUCTORS
new
my $r = Time::R>new($start);
my $r = Time::R>new($start, end => $end, years => $year, months => $months,
weeks => $weeks, days => $days, hours => $hours, minutes => $minutes,
seconds => $seconds);
Creates a Time::R object starting at $start
, and optionally ending at $end
. Every argument except $start
is optional and can be in any order.
$start

This should be a Time::C object representing the starting time.
end => $end

This should be a Time::C object optionally specifying the ending time. Defaults to
undef
. years => $years

This should be the number of years between each recurrence. Defaults to
0
. months => $months

This should be the number of months between each recurrence. Defaults to
0
. weeks => $weeks

This should be the number of weeks between each recurrence. Defaults to
0
. days => $days

This should be the number of days between each recurrence. Defaults to
0
. hours => $hours

This should be the number of hours between each recurrence. Defaults to
0
. minutes => $minutes

This should be the number of minutes between each recurrence. Defaults to
0
. seconds => $seconds

This should be the number of seconds between each recurrence. Defaults to
0
.
ACCESSORS
start
my $start = $r>start;
$r>start = $start;
$r = $r>start($new_start);
Returns or sets the Time::C object representing the starting time of the recurrence. Setting this also calls $r>reset()
.
If the form $r>start($new_start)
is used, it likewise updates the start but returns the entire object.
current
my $current = $r>current;
$r>current = $current;
Returns or sets the Time::C object representing the current time of the current recurrence.
This may get changed by $r>next
, $r>upcoming
, $r>latest
, $r>until
, and $r>reset
.
end
my $end = $r>end;
$r>end = $end;
Returns or sets the Time::C object representing the end time of the recurrence.
years
my $years = $r>years;
$r>years = $years;
$r>years += 10;
$r>years++;
$r>years;
Returns or sets the number of years between each recurrence. Setting this also calls $r>reset()
.
months
my $months = $r>months;
$r>months = $months;
$r>months += 12;
$r>months++;
$r>months;
Returns or sets the number of months between each recurrence. Setting this also calls $r>reset()
.
weeks
my $weeks = $r>weeks;
$r>weeks = $weeks;
$r>weeks += 52;
$r>weeks++;
$r>weeks;
Returns or sets the number of weeks between each recurrence. Setting this also calls $r>reset()
.
days
my $days = $r>days;
$r>days = $days;
$r>days += 7;
$r>days++;
$r>days;
Returns or sets the number of days between each recurrence. Setting this also calls $r>reset()
.
hours
my $hours = $r>hours;
$r>hours = $hours;
$r>hours += 24;
$r>hours++;
$r>hours;
Returns or sets the number of hours between each recurrence. Setting this also calls $r>reset()
.
minutes
my $minutes = $r>minutes;
$r>minutes = $minutes;
$r>minutes += 60;
$r>minutes++;
$r>minutes;
Returns or sets the number of minutes between each recurrence. Setting this also calls $r>reset()
.
seconds
my $seconds = $r>seconds;
$r>seconds = $seconds;
$r>seconds += 60;
$r>seconds++;
$r>seconds;
Returns or sets the number of seconds between each recurrence. Setting this also calls $r>reset()
.
METHODS
next
my $next = $r>next();
Sets $r>current
to and returns the next recurrence as a Time::C object. If the next time would happen after the $r>end
, it instead returns undef
and leaves $r>current
alone.
upcoming
my $upcoming = $r>upcoming();
Sets $r>current
to and returns the next time the recurrence occurs as a Time::C object based on the current time. If the next time would happen after the $r>end
, it instead returns undef
and leaves $r>current
alone.
latest
my $latest = $r>latest();
Sets $r>current
to and returns the latest time the recurrence occurs as a Time::C object based on the current time.
until
my @until = $r>until($end);
Returns all the recurrences that will happen from $r>current
until $end
(which should be a Time::C object), and updates $r>current
to the last one returned if any. If $r>end
is defined and $end
is after, it will instead use $r>end
as the limit.
reset
$r>reset();
Resets $r>current
to $r>start
.
SEE ALSO
AUTHOR
Andreas Guldstrand <andreas.guldstrand@gmail.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2016 by Andreas Guldstrand.
This is free software, licensed under:
The MIT (X11) License