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);
# "2016-02-29T00:00:00Z"
my $first = $r->next();
# "2016-03-31T00:00:00Z
my $second = $r->next();
# resets $r->next()
$r->reset();
# 2016-10-31T00:00:00Z" (depending on current time)
my $upcoming = $r->upcoming();
# "2016-09-30T00:00:00Z" (depending on current time)
my $latest = $r->latest();
# ("2016-09-30T00:00:00Z", "2016-10-31T00:00:00Z", "2016-11-30T00:00:00Z",
# "2016-12-31T00:00:00Z")
my @dates = $r->until(Time::C->new(2017,1,1));
# "2017-01-31T00: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