NAME
Date::Manip::Range - Parses and holds a date range
SYNOPSIS
use Date::Manip::Range;
my $object = Date::Manip::Range->new();
$object->method();DESCRIPTION
Date::Manip::Range parses and holds a date range. The range is defined by a start and end point. The module accepts ranges as a single string, start and end dates, or a list of dates.
Single string
The string has two dates separated by a range operator. Some examples...
my $range = Date::Manip::Range->new( {range => 'today - tommorrow'} );
my $range = Date::Manip::Range->new( {range => 'Jan 21 through Feb 3'} );
my $range = Date::Manip::Range->new( {range => '2015-01-29 to 2015-02-03'} );
my $range = Date::Manip::Range->new( {range => 'from Jan 21 to Feb 3'} );
my $range = Date::Manip::Range->new( {range => 'between Jan 21 and Feb 3'} );Date::Manip::Range recognizes the following range operators...
Date::Manip::Range splits the string on the operator, extracting the start and end points. It creates Date::Manip objects from those two points. The dates can be anything parsable by Date::Manip.
Start and end dates
Pass two values and Date::Manip::Range assumes they are the start and end points of the range. These values can be strings parsable by Date::Manip or actual Date::Manip objects.
my $range = Date::Manip::Range->parse( 'today', 'tommorrow' );
my $range = Date::Manip::Range->parse( '2015-02-03', '2015-01-29' );
my $day1 = Date::Manip::Date->new( '2015-01-29' );
my $day2 = Date::Manip::Date->new( '2015-02-03' );
my $range = Date::Manip::Range->new( $day1, $day2 );List of dates
With three or more dates, Date::Manip::Range assumes that the earliest and latest values are the start and end. It discards everything else.
Like the options above, dates can be strings, Date::Manip objects, or any combination of the two.
Important Facts
- Date strings can be anything parsable by Date::Manip.
- Dates can be in any order. The earliest becomes the start.
- Range operators are case insensetive.
METHODS & ATTRIBUTES
new
Like every other Moose object, you can pass default values for any attributes. new ensures that the "start" date always comes before the "end" date. It swaps the two if necessary.
In addition, new also accepts a parse attribute. parse is a date range in the form of a string. new calls the "parse" method, passing it this string. "parse" sets the "start" and "end" dates appropriately.
Check the "error" attribute for problems.
parse
This method takes any acceptable input for a range, parses the values, and configures the Date::Manip::Range object. parse returns true on success or false if any of the dates are invalid. "error" tells you which date.
includes
This method tells you if a given date falls within the range. A true value means that the date is inside of the range. false says that the date falls outside of the range.
The date can be a string or Date::Manip object. Strings accept any valid input for Date::Manip::Date. If the date is invalid, inside returns an error message that Perl evaluates as false.
Note that inside does not tell you if the date comes before or after the range. That didn't seem relevant.
include_start / include_end
These attributes mark inclusive or exclusive ranges. By default, a range includes dates that fall on the start or end. For example...
$range->new( {date => '2015-01-15 to 2015-01-31'} );
# returns true because the start is included
$range->includes( '2015-01-15' );
# retruns true because it is between the start and end
$range->includes( '2015-01-20' );
# retruns true because the end is included
$range->includes( '2015-01-31' );For exclusive ranges, set one or both of these values to false.
$range->new( {date => '2015-01-15 to 2015-01-31'} );
$range->include_start( 0 );
# returns false because the start is excluded
$range->includes( '2015-01-15' );
# retruns true because it is between the start and end
$range->includes( '2015-01-20' );
# retruns true because the end is included
$range->includes( '2015-01-31' );is_valid
This method tells you if the object holds a valid date range. Use this after calling "new". If anything failed (invalid dates), is_valid returns false.
error
Returns the last date parsing error. Date::Manip::Range sets this attributes when any method encounters an invalid date. An empty string indicates no problem. You should check this value after calling methods such as "parse" or "includes".
start / end
The Date::Manip::Date objects representing the end points of the range. Note that you cannot change these values. Use "parse" to do that.
operator
The last range operator used when parsing a string. When strinifying a range, Date::Manip::Range re-uses this same operator. The default operator is to.
BUGS/CAVEATS/etc
Date::Manip::Range only supports English range operators. Translations welcome.
AUTHOR
Robert Wohlfarth <rbwohlfarth@gmail.com>
SEE ALSO
LICENSE
Copyright (c) 2015 Robert Wohlfarth
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with NO WARRANTY of any kind.