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

cpanm Time::C

perl -MCPAN -e shell
install Time::C