NAME

Range::Date - Ranges as applied to dates

SYNOPSIS

 use Range::Date;
 
 # Create a new range
 my $range = Range::Date->new('1970-01-01', '2012-02-27/2012-03-02');
 
 # Test if a value is in range
 print "in range\n"     if  $range->in('2012-02-29');
 print "not in range\n" if !$range->in('2012-12-21');
 
 # Add values to range
 $range->add('2012-02-24/2012-02-26');
 
 # Get full list of values
 my @list = $range->range();
 print join q{ }, @list;
 # Prints:
 # 1970-01-01 2012-02-24 2012-02-25 2012-02-26 2012-02-27 2012-02-28 ...
 # 2012-02-29 2012-03-01 2012-03-02
 
 # Get collapsed string representation
 my $string = $range->range("\n");
 print "$string\n";
 # Prints:
 # 1970-01-01
 # 2012-02-24/2012-03-02
 
 # Get range size
 my $size = $range->size();
 print "$size";                     # Prints: 9

DESCRIPTION

This module implements ranges of dates using the same API as other Range::* modules.

Input date formats are subset of ISO 8601; only two are supported: YYYY-MM-DD and YYYY-MM for month-only dates.

METHODS

See Range::Object.

DIAGNOSTICS

Invalid input date

add() will throw this exception when input date item is invalid. This could mean either invalid date format or invalid date, i.e. Feb 29th on non-leap year.

Invalid input date in range

add() will throw this exception when there is invalid date in input range.

Last date in range cannot be earlier than first date

add() will throw this exception if date range is reversed, i.e. last comes first.

Invalid input range

This exception is thrown when two dates comprising a range appear to be valid but Date::Range fails to create a new range.

Can't mix YYYY-MM and YYYY-MM-DD input formats

add() will throw an exception with this message if input range contains both month-only and full date. This is more a sanity check than technical limitation; mixing two formats is probably the result of an error.

Invalid input 'item': no ISO 8601 dates found

This exception is thrown by add() when it is fed with something that is not a date in ISO 8601 format.

DEPENDENCIES

This module is dependent on the following modules: List::Util, Date::Simple, Date::Range.

BUGS AND LIMITATIONS

Only two formats of dates are supported out of ISO 8601 standard.

Adding a range that intersects already existing range will not result in creation of a wider range; current implementation will store new range along with existing one and then return both of them. This needs to be resolved in subsequent releases.

There are no known bugs in this module. Please report problems to author, patches are welcome.

AUTHOR

Alexander Tokarev <tokarev@cpan.org>.

LICENSE AND COPYRIGHT

Copyright (c) 2011 Alexander Tokarev.

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