NAME

Date::Calc::Iterator - Iterate over a range of dates

SYNOPSIS

  use Date::Calc::Iterator;

  # This puts all the dates from Dec 1, 2003 to Dec 10, 2003 in @dates1
  my $iterator = Date::Calc::Iterator->new(from => [2003,12,1], to => [2003,12,10]) ;
  while (my $date = $iterator->next) {
      # will produce [2003,12,1], [2003,12,2] ... [2003,12,10]
  }

Or as ISO 8601 format date strings:

  use Date::Calc::Iterator;

  my $iterator = Date::Calc::Iterator->new(from => '2003-12-01', to => '2003-12-10');
  while (my $date = $iterator->next) {
      # will produce '2003-12-01', '2003-12-02' ... '2003-12-10'
  }

ABSTRACT

Date::Calc::Iterator objects are used to iterate over a range of dates, day by day or with a specified step.

The from and to dates can either be specified as "[$year,$month,$day]" arrayrefs, or as ISO 8601 format date strings (where Christmas Day 2018 is either '2018-12-31' or '20181231'.

The method next() will return each time a date in the same format that you specified the from date, or "undef" when finished.

WARNING

This module is little and simple. It solves a little problem in a simple way. It doesn't attempt to be the smarter module on CPAN, nor the more complete one. If your problem is more complicated than this module can solve, you should go and check DateTime::Event::Recurrence, which solves a so broad range of problems that yours can't fall out of it.

Probabily this module won't evolve a lot. Expect bug fixes, minor improvements in the interface, and nothing more. If you need to solve bigger problems, you have two choices: vivifying a 2.x version of the module (after contacting me, of course) or using DateTime::Event::Recurrence and its brothers.

Anyway, I left the name Iterator, and not Iterator::Day or DayIterator, for example, so that the module can evolve if the need be. Who knows? Maybe one day I could need to make it iterate over weekdays, or over moon phases... let's leave the way open, time will tell.

DESCRIPTION

new

Creates a new object. You must pass it the end points of a date interval as array references or ISO 8601 date strings.

  $i = Date::Calc::Iterator->new( from => [2003,12,1], to => [2003,12,10] )

"from" and "to" are, obviously, required.

Optionally, you can specify a custom step with the "step" key, for example:

  $i = Date::Calc::Iterator->new(
           from => '2003-12-01',
           to   => '2003-12-31',
           step => 7 );

will iterate over December 2003, week by week, starting from December 1st.

Returns the next date; in list context it returns an array containing year, month and day in this order, or "undef" if iteration is over; in scalar context, it returns a reference to that array, or "undef" if iteration is over.

AUTHOR

Marco Marongiu, <bronto@cpan.org>

THANKS

Thanks to Steffen Beyer, for writing his Date::Calc and for allowing me to use his namespace.

Thanks to Neil Bowers, who added the support for ISO 8601 format dates, and the other changes in the 1.01 release.

Blame on me, for being so lazy (or spare-time-missing) that I didn't make this module compatible with the Date::Calc::Object interface.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.