- CLASS METHODS
- OBJECT METHODS
- to_secs(), duration()
- to_string([$format = Date::Rel::Format::simple])
- 'bool', to_bool()
- '0+', to_number()
- '+', sum($arg)
- '+=', add($arg)
- '-', difference($arg)
- '-=', subtract($arg)
- '*', product($num)
- '*=', multiply($num)
- '/', quotient($num)
- '/=', divide($num)
- 'neg', negated() (unary '-')
- '<=>', compare($arg)
- 'eq', is_same($arg)
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.
$seconds seconds long
Creates relative date from string in the following formats:
- Simple format [duration]
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.
- ISO8601 time period format [duration]
- ISO8601 time interval format [interval]
Any part can be absent or negative.
If a given string is in invalid format, empty object returned with
error() set to
If you want it to throw an exception on invalid inputs, see Date::strict.
Creates interval from two dates so that $from + $rel == $till.
If timezones of
$till differ, then
$from is converted to
Clones another object
Creates duration. Valid keys are
Set relative date from arguments (can be anything that
Set relative date from arguments (can be anything that
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 (
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
- Date::Rel::FORMAT_ISO8601I (for intervals only)
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.
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.
$arg is a date object, the result is the same as
$date + $rel, i.e. date.
$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
$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
$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
$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)
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
quotient(), but changes current object instead of creating new one.
Changes sign of YMDhms
negated(), but changes current object instead of creating new one.
$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.
$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
- Storable serialization/deserealization