Date::Manip::Delta(3) User Contributed Perl Documentation Date::Manip::Delta(3)
Date::Manip::Delta - Methods for working with deltas
$date = new Date::Manip::Delta;
This module contains functions useful in parsing and manipulating deltas. As used in this
module, a delta refers only to the amount of time elapsed. It includes no information
about a starting or ending time.
There are several concepts involved in understanding the properties of a delta.
A delta consists of 7 fields: years, months, weeks, days, hours, minutes, and seconds,
usually expressed as a colon-separated string. For example:
refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4 days, 5 hours, 6
minutes, and 7 seconds long.
A delta can be normalized or not. A normalized delta has values which have been made
consistent with the type of data they represent. For example, a delta of:
is not normalized since 70 seconds is better expressed as 1 minute 10 seconds. The
normalized form of this delta would be:
Deltas are automatically converted to a normalized form in almost all functions.
sets of fields
When normalizing a delta, fields are grouped together in sets where the exact
relationship is known between all fields in the set.
For example, in a normal delta, it is known that there are exactly 60 seconds in a
minute, exactly 60 minutes in an hour, etc.
It is NOT known how many weeks are in a month however. So, the year and month fields
form one set, and the weeks, days, hours, minutes, and seconds form a second set.
When normalizing a delta, no data from one set will ever be mixed with data from
As a result, the following delta is normalized:
Although 8 weeks is clearly more than 1 month, we don't know the relationship between
the two, so they don't mix.
An exact delta is one which does not include any fields which cannot be exactly
written in terms of seconds. For example, a delta which includes a year or month field
can never be exact since there is no exact length for either.
So, the delta:
is not exact, but the delta:
Deltas can refer to changes in either the full calendar, or they can refer to a
Business deltas have the added complexity that there is no definite relationship
between the number of work days in a work week (there may be a holiday during the
week). As a result, there are three sets of fields: year/month, week,
day/hour/minute/second. An exact business delta will not have a year, month, or week
There IS a definite relationship between hours and days, but it is probably not 24
hours = 1 day. Common definitions of a work day include 8 hours long (09:00-17:00) or
9 hours long (08:00-17:00), and any other definition may be included may be defined as
long as the start time is earlier in the day than the end time. The config variables
WorkDayBeg, WorkDayEnd, and WorkDay24Hr can be used to defined the length of the work
Each set of fields has a sign associated with it. For example, the delta "1 year ago"
is written as:
Since there is no mixing of data between sets of fields, you can end up with a delta
with two (or three in the case of business deltas) signs. So, the following is a fully
normalized business delta:
Note that for a fully normalized delta, the leading field in each set of fields will
always have a sign, even when it is redundant or unnecessary.
In a normalized delta, all fields in a set will have the same sign.
err Please refer to the Date::Manip::Obj documentation for these methods.
$err = $delta->parse($string [,$business]);
This takes a string and parses it to see if it is a valid delta. If it is, an error
code of 0 is returned and $delta now contains the value of the delta. Otherwise, an
error code of 1 is returned.
A valid delta is in one of two forms: colon or expanded.
The colon format is:
In the colon format, from 1 to 7 of the fields may be given. For example +D:+H:+MN:+S
may be given to specify only four of the fields. No spaces may be present in the
colon format. It is allowed to omit some of the fields. For example 5::3:30 is valid.
In this case, missing fields default to the value 0.
The expanded format is:
+Yy +Mm +Ww +Dd +Hh +MNmn +Ss
+4 hours +3mn -2second
+ 4 hr 3 minutes -2
4 hour + 3 min -2 s
4 hr 2 s (note that minutes are omitted)
A field in the expanded format (+Yy) is a sign, a number, and a string specifying the
type of field. The sign is "+", "-", or absent (defaults to the next larger element).
The valid strings (in English) specifying the field type are:
y: y, yr, year, years
m: m, mon, month, months
w: w, wk, ws, wks, week, weeks
d: d, day, days
h: h, hr, hour, hours
mn: mn, min, minute, minutes
s: s, sec, second, seconds
Other languages have similar abbreviations.
Also, the "seconds" string may be omitted. The sign, number, and string may all be
separated from each other by any number of whitespace. The string specifying the unit
must be separated from a following number by whitespace or a comma, so the following
example will NOT work:
At minimum, it must be expressed as:
4 hours, 3 minutes
In the the expanded format, all fields must be given in the order: Y M W D H MN S.
Any number of them may be omitted provided the rest remain in the correct order.
Most languages also allow a word to specify whether the delta is an amount of time
after or before a fixed point. In English, the word "in" refers to a time after a
fixed point, and "ago" refers to a point before a fixed point. So, the following
deltas are equivalent:
in 1 year
and the following are equivalent
1 year ago
The word "in" is completely ignored. The word "ago" has the affect of reversing all
signs that appear in front of the components of the delta. In other words, the
following two strings are identical:
-12 yr 6 mon ago
+12 yr +6 mon
(don't forget that there is an implied minus sign in front of the 6 in the first
string because when no sign is explicitly given, it carries the previously entered
The in/ago words only apply to the expanded format, so the following is invalid:
A delta may be business mode, or non-business mode. By default, a delta is treated as
a non-business mode delta, but this can be changed in two different ways.
The first way to make a delta be business mode is to pass in the 2nd argument to the
function that is non-zero. If this is done, the delta will be a business delta by
The second way to specify whether a delta is business or non-business is to include a
key word in the string that is parsed. When this is done, these strings override any
value of the $business argument.
Most languages include a word like "business" which can be used to specify that the
resulting delta is a business mode delta or a non-business delta. Other languages have
equivalent words. The placement of the word is not important. Also, the "business"
word can be included with both types of deltas, so the following are valid and
in 4 hours business
There are also words "exact" or "approximate" which serve to force the delta to be
non-business mode. For backward compatibility, both are available and serve the same
purpose (they no longer determine whether the delta is exact or not... that is
determined only by the fields that are included as described above).
$err = $delta->set($field,$val);
This explicitly sets one or more fields in a delta.
$field can be any of the following:
delta [Y,M,W,D,H,MN,S] sets the entire delta
business [Y,M,W,D,H,MN,S] sets the entire delta
normal [Y,M,W,D,H,MN,S] sets the entire delta
y YEAR sets one field
mode business, normal
An error is returned if an invalid value is passed in.
When setting the entire delta with "business" or "normal", it flags the delta as a
business or non-business delta respectively. When setting the entire delta with
"delta", the flag is left unchanged.
$out = $delta->printf($in);
This takes a string ($in) which may contain any number of special formatting
directives. These directives are replaced with information contained in the delta.
Everything else in the string is returned unmodified.
A directive always begins with '%'. They are described in the section below in the
section PRINTF DIRECTIVES.
$date2 = $delta->calc($date1 [,$subtract]);
$delta3 = $delta1->calc($delta2 [,$subtract]);
Please refer to the Date::Manip::Calc documentation for details.
$flag = $delta->type($op);
This tests to see if a delta is of a certain type. $op can be;
business : returns 1 if it is a business delta
exact : returns 1 if it is exact
$val = $delta->value();
@val = $delta->value();
This returns the value of the delta. In scalar context, it returns the printable
string (equivalent to the printf directive '%Dt'). In list context, it returns a list
undef is returned if there is no valid delta stored in $delta.
The following printf directives are replaced with information from the delta. Directives
may be replaced by the values of a single field in the delta (i.e. the hours or weeks
field), the value of several fields expressed in terms of one of them (i.e. the number of
years and months expressed in terms of months), or the directive may format either the
entire delta, or portions of it.
These are directives which print simple characters. Currently, the only one is:
%% Replaced by a single '%'
As an example:
$delta->printf('|A %% B|');
=> |A % B|
Directives to print out a single field
The following directive is used to print out the value of a single field. Spaces are
included here for clarity, but are not in the actual directive.
% [+] [pad] [width] Xv
Here, X is one of (y,M,w,d,h,m,s). The directive will print out the value for that
field (in the normalized delta).
If a '+' is included immediately after the '%', a sign will always be included. By
default, only negative values will include a sign.
'width' is any positive integer (without a sign). If 'width' is included, it sets the
length of the output string (unless the string is already longer than that, in which
case the 'width' is ignored).
If 'pad' is included, it may be the character '<', '>', or '0'. It will be ignored
unless 'width' is included. If the formatted delta field is shorter than 'width', it
will be padded with spaces on the left (if 'pad' is '<'), or right (if 'pad' is '>'),
or it will be padded on the left (after any sign) with zeroes (if 'pad' is '0').
In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
=> |Month: 2|
=> |Day: +0004|
=> |Day: +4|
=> |Day: 7 |
Directives to print out several fields in terms of one of them
The following directive is used to print out the value of several different fields,
expressed in terms of a single field.
% [+] [pad] [width] [.precision] XYZ
Here, X, Y, and Z are each one of (y,M,w,d,h,m,s). The directive will print out the
value for fields Y through Z expressed in terms of field X.
Y must come before Z in the sequence (y,M,w,d,h,m,s) or it can be the same as Z.
So, to print the day and hour fields in terms of seconds, use the directive:
Any time all of X, Y, and Z are from a single set of fields, exact relationships are
If the X, Y, and Z fields do not all belong to the same set of fields, approximate
relationships are used.
For non-business deltas, an approximate relationship is needed to link the Y/M part of
the delta to the W/D/H/Mn/S part. The relationship used is that a year is assigned a
length of 365.2425 days.
For business deltas, the relationship between weeks and days is set to be the length
of the business week (as defined using the WorkWeekBeg and WorkWeekEnd config
variables). Also, a factor of X/7 * 365.2425 (where X is the number of days in a work
week) is used to determine the number of work days in a year.
If 'precision' is included, it is the number of decimal places to print. If it is not
included, but 'width' is included, precision will be set automatically to display the
maximum number of decimal places given 'width'.
If 'pad' is included, it may be the character '<', '>', or '0', and is used in the
same way as printing out a single field.
In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
1 year, 2 months, 3 weeks is approximately
Directives to print out portions of the delta
The following directives may be used to print out some or all of a delta.
% [+] [pad] [width] Dt
% [+] [pad] [width] DXY
The first directive will print out the entire delta.
The second will print out the delta from the X to Y fields inclusive (where X and Y
are each one of (y,M,w,d,h,m,s) and X must come before Y in the sequence).
'pad' is optional and can be either '<' or '>' meaning to pad on the left or right
with spaces. It defaults to '<'.
If a '+' is included immediately following the '%', every field will have a sign
attached. Otherwise, only the leftmost field in each set of fields will include a
BUGS AND QUESTIONS
Please refer to the Date::Manip::Problems documentation for information on submitting bug
reports or questions to the author.
Date::Manip - main module documentation
This script is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
Sullivan Beck (firstname.lastname@example.org)
perl v5.12.1 2010-01-12 Date::Manip::Delta(3)