Date::Rel - Relative date object.
Relative date is a period of time and is used for date calculations.
Reldate consists of 6 units - seconds, minutes, hours, days, months and years.
Relative date may be interval (bound to a certain date) or duration (not bound). These two are almost identical in operations and API. The main difference is that duration may convert one unit to another inaccurate while interval always returns accurate numbers.
Creates duration $seconds seconds long
Creates relative date from string in the following formats:
1Y 2M 3D 4h 5m 6s
Possible keys: 'Y' or 'y' - years, 'M' - months, 'W' or 'w' - weeks, 'D' or 'd' - days, 'h' - hours, 'm' - minutes, 's' - seconds.
Weeks (w/W) are immediately converted to days (x7) and do not persist in relative date object.
Any part can be absent or negative.
If a given string is in invalid format, empty object returned with error() set to Date::Error::parser_error.
If you want it to throw an exception on invalid inputs, see Date::strict.
Creates interval from two dates so that $from + $rel == $till.
$from and $till can be Date objects or any type that one-argument Date constructor supports.
If timezones of $from and $till differ, then $from is converted to $till's timezone.
Clones another object
Creates duration. Valid keys are year, month, day, hour, min, sec
Set relative date from arguments (can be anything that new() supports).
Set relative date from arguments (can be anything that new_ymd() supports).
Get/set number of years in relative date
Get/set number of month in relative date
Get/set number of days in relative date
Get/set number of hours in relative date
Get/set number of minutes in relative date
Get/set number of seconds in relative date
Get/set date that object is bound to. Also changes the behaviour of object (duration/interval).
For interval returns the end of the interval as date, for duration returns undef.
For interval, returns accurate number of seconds in interval. This applies for other duration getters as well (to_mins(), ...etc).
Otherwise, converts duration to number of seconds. If any of day/month/year are non-zero, then this value can be inaccurate because one need to know exact dates to calculate exact number of seconds.
For such calculations the following assumptions are made:
Converts relative date to number of minutes. See to_secs() for accuracy info (if has day/month/year).
Converts relative date to number of hours. See to_secs() for accuracy info (if has day/month/year).
Converts relative date to number of days. See to_secs() for accuracy info (if has sec/min/hour/month/year).
Converts relative date to number of months. See to_secs() for accuracy info (if has sec/min/hour/day).
Converts relative date to number of years. See to_secs() for accuracy info (if has sec/min/hour/day).
Returns string in one of the following formats:
4M 15D 123s
ISO 8601 duration format
ISO 8601 interval format
If current object is a duration, fallbacks to FORMAT_ISO8601D
Any of YMDhms can be absent or negative. If all the parts YMDhms are 0, then "" is returned.
Weeks are only for input, they are converted to days on input.
Same as to_string()
Returns error occured during parsing relative date from string (if any) as XS::STL::ErrorCode object.
Called implicitly in boolean context. Returns FALSE, if sec = 0 and min = 0 and .... year = 0, i.e. duration = 0. Otherwise TRUE.
If $arg is a date object, the result is the same as $date + $rel, i.e. date.
$date + $rel
Otherwise, converts $arg to relative date, adds it to the current object and returns new relative date.
my $rel = 2*MONTH;
say $rel + MONTH; # 3M
say $rel + '30D'; # 2M 30D
say $rel + rdate(1,2,3); # 1Y 4M 3D
Converts $arg to relative date and adds it to the current object
my $rel = 2*MONTH;
$rel += '16h'; # 2M 16h
$rel += rdate(sec => 10, min => 20); # 2M 16h 20m 10s
$rel += $rel; # 4M 32h 40m 20s
Converts $arg to relative date, subtracts it from the current object and returns new relative date.
my $rel = 2*MONTH;
say $rel - MONTH; # 1M
say '30D' - $rel; # -2M 30D
say $rel - rdate(1,2,3); # -1Y -3D
Converts $arg to relative date and subtracts it from the current object.
Multiplies relative date by $num. $num can be fractional but the result is always integer.
$rel = "1M 1D";
print $rel * 2; # 2M 2D
print rdate("10h")->multiply(10); # 100h
No normalization are made, i.e. 12h*2 = 24h is not normalized to 1D because that would be inaccurate (on DST border day for example, 1D is 25 or 23h)
Same as product(), but changes current object instead of creating new one.
Divides relative date by $num. $num can be fractional but the result is always integer.
System will denormalize values if in another way (rounding) precision loses are bigger, for example "1Y" / 2 = "6M" (without denormalization it would be 0).
This applies even if units are not converted accurate. In this case assumptions mentioned in to_secs() are made.
$rel = "2Y";
print $rel/2; # 1Y
print $rel/4; # 6M
print rdate("1D")/3; # 8h
print (rdate("1D")/3)*3; # 24h
print MONTH/2; # "15D 5h 14m 32s"
P.S. Keep in mind that ($rel / N) * N is not always equals $rel, as well as ($rel * N) / N
Same as quotient(), but changes current object instead of creating new one.
Changes sign of YMDhms
Same as negated(), but changes current object instead of creating new one.
Converts $arg to relative date, compares 2 relative dates and returns -1, 0 or 1.
Relative dates are compared using duration(), therefore 2 dates can be equal even if they consist of different components. If you want full equality test, use 'eq'.
MONTH > YEAR; # false
rdate("1Y 1M") > YEAR; #true
12*MONTH == YEAR; #true
12*MONTH eq YEAR; #false
Returns TRUE only if 2 reldates are fully identical.
$reldate = rdate("1Y 2M");
$reldate == "1Y 2M"; # true
$reldate == "14M"; # true
$reldate eq "1Y 2M"; # true
$reldate eq "14M"; # false
If one of the arguments is an interval, then the other has to be interval too, otherwise returns FALSE.
If reldate is a duration, returns 0.
Otherwise, converts $arg to date and:
Returns -1 if date is greater than the end of the interval.
Returns 0 if date is between the interval (including the edges).
Returns 1 otherwise.
my $rel = rdate("2019-01-10", "2019-01-11");
$rel->includes("2019-01-09"); # 1
$rel->includes("2019-01-11 00:00:01"); # -1
$rel->includes("2019-01-10"); # 0
$rel->includes("2019-01-10 10:00:00"); # 0
$rel->includes("2019-01-11"); # 0
To install Date, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.