The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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

Time::C
Time::D

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