NAME¶
Date::Manip::Delta - Methods for working with deltas
SYNOPSIS¶
use Date::Manip::Delta;
$date = new Date::Manip::Delta;
DESCRIPTION¶
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.
- standard and business delta
- Deltas can refer to changes in either the full calendar
(standard deltas), or they can refer to a business calendar.
With a business delta, non-business days are ignored. Typically, this
includes holidays and weekends. In addition, the part of the day outside
of business hours is also ignored, so a day may only run from 08:00 to
17:00 and everything outside of this is ignored.
The length of a work day is usually not 24 hours. It is defined by the start
and end of the work day and is set using the config variables: WorkDayBeg
and WorkDayEnd (WorkDay24Hr may be used to specify a 24-hour work day).
The work week is defined using the config variables: WorkWeekBeg and
WorkWeekEnd.
Daylight saving time will have no impact on business calculations because
time changes occur at night (usually on the weekends) outside of business
hours. As such, they are ignored in business calculations.
- fields
- A delta consists of 7 fields: years, months, weeks, days,
hours, minutes, and seconds, usually expressed as a colon-separated
string. For example:
1:2:3:4:5:6:7
refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4 days, 5
hours, 6 minutes, and 7 seconds long.
- normalized
- 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:
0:0:0:0:0:10:70
is not normalized since 70 seconds is better expressed as 1 minute 10
seconds. The normalized form of this delta would be:
0:0:0:0:0:11:10
By default, deltas are converted to a normalized form in most functions that
create/modify a delta, but this can be overridden.
- 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, there is an exactly known relationship between seconds and
minutes (Date::Manip ignores leap seconds, so there are always 60 seconds
in a minute), so they will be in one set.
Likewise, the relationship between years and months is known, so they will
be in one set. There is no known relationship between months and weeks
though, so they will be in separate sets.
A standard (i.e. non-business) delta contains 3 sets of fields:
approximate: year, month
semi-exact: week, day
exact: hour, minute, second
The following known relationships exist:
1 year = 12 months
1 week = 7 days
1 hour = 60 minutes
1 minute = 60 seconds
The following semi-approximate relationships are used to link the semi-exact
and exact fields when required:
1 day = 24 hours
The following approximate relationship is used to link the approximate
fields to the semi-exact fields when required:
1 year = 365.2425
Business deltas differ slightly, Since daylight saving times effects are
ignored, the length of the work day is constant, but due to there being
holidays, the length of a week is not known, so a business delta has the
following sets of fields:
approximate: year, month
semi-exact: week
exact: day, hour, minute, second
and the relationships used are:
1 year = 12 months
1 day = length of business day
1 hour = 60 minutes
1 minute = 60 seconds
The semi-approximate relationship may be used to link the semi-approximate
and exact fields together:
1 week = X (length of business week in days)
and the following approximate relationship may be used:
1 year = X/7 * 365.2425
When normalizing a delta, no data from one set will ever be mixed with data
from another set.
As a result, the following delta is normalized:
0:3:8:0:0:0:0
Although 8 weeks is clearly more than 1 month, we don't know the
relationship between the two, so they don't mix.
- exact, semi-exact, and approximate deltas
- An exact delta is one which every value is of an exactly
known length (i.e. it only includes the exact fields listed above).
A semi-exact delta is a delta which includes the exact fields as well as
semi-exact ones.
An approximate delta can include any of the fields.
So, the delta:
0:3:8:0:0:0:0
is approximate. The delta:
0:0:0:0:30:0:0
is exact. The delta:
0:0:0:1:30:0:0
is semi-exact (if it is non-business) or exact (if it is business).
The term "semi-exact" needs a little explanation. Date::Manip
tries to do things in a way which humans think of them. It is immediately
recognized that the approximate fields are of completely unknown length,
and the exact fields are of known length. The "semi-exact"
fields are termed such since humans have a way of looking at them which is
consistent, even if it is not exact.
For example, a day is thought of as the same wall clock time on two
successive days, so from noon on one day to noon the next day is one day.
Usually that is 24 hours (for standard deltas), but if you cross a
daylight saving time change, it might be 23 or 25 hours (or something
different if a very irregular time change occurs). So where possible, in a
standard delta, a day field will change the date, but leave the time
alone.
Likewise, a business week is thought of as 7 days (i.e. Wednesday to
Wednesday) regardless of whether there was a holiday in there.
- signs
- Each field has a sign associated with it. For example, the
delta "1 year ago" is written as:
-1:0:0:0:0:0:0
The sign of any field is optional, and if omitted, it is the same as the
next higher field. So, the following are identical:
+1:2:3:4:5:6:7
+1:+2:+3:+4:+5:+6:+7
Since there is no mixing of data between sets of fields, you can end up with
a delta with as many as four signs. So, the following is a fully
normalized business delta:
+1:0:-3:+3:1:0:0
- fractional values
- Fractional fields are allowed such as:
1.25 days
1.1 years
When parsing a delta with fractional fields, the delta will ALWAY be
normalized using the exact, semi-exact, and approximate relationships
described above.
For example, for a non-business delta, a delta of 1.1 years will use the
following relationships:
1 year = 365.2425 days
1 year = 12 months
1 day = 24 hours
Since the delta includes approximate fields, as much of the 1.1 year portion
of the delta will be stored in the approximate fields as possible.
Using the above approximate relationships, we can see that:
1 month = 365.2425/12 days = 30.436875 days
so
1.1 years
= 1 year, 1.2 months
= 1 year, 1 month, 6.087375 days
= 1 year, 1 month, 6 days, 2 hours, 5 minutes, 49 seconds
Fractional seconds will be discarded (no rounding).
METHODS¶
- new
- new_config
- new_date
- new_delta
- new_recur
- base
- tz
- is_date
- is_delta
- is_recur
- config
- err
- Please refer to the Date::Manip::Obj documentation for
these methods.
- parse
-
$err = $delta->parse($string [,$business] [,$no_normalize]);
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 and an error condition is
set in the delta.
A valid delta is in one of two forms: compact or expanded.
The compact format is a colon separated list of numbers (with optional
signs):
Examples:
0:0:0:0:4:3:-2
+4:3:-2
+4::3
In the compact 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 compact 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 has the fields spelled out in some language specific
form:
Examples:
+4 hours +3mn -2second
+ 4 hr 3 minutes -2
4 hour + 3 min -2 s
4 hr 2 s
A field in the expanded format has an optional sign, a number, and a string
specifying the type of field. If the sign is absent, it defaults to the
sign of the next larger element. So the following are equivalent:
-4 hr 3 min 2 sec
-4 hr -3 min -2 sec
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.
The "seconds" string may be omitted. The sign, number, and string
may all be separated from each other by any amount 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:
4hours3minutes
At minimum, it must be expressed as:
4hours 3minutes
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. Numbers may be spelled out, so
in two weeks
in 2 weeks
both work.
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:
1:0:0:0:0:0:0
in 1 year
and the following are equivalent
-1:0:0:0:0:0:0
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 sign).
The in/ago words only apply to the expanded format, so the following is
invalid:
1:0:0 ago
A delta may be standard (non-business) or business. By default, a delta is
treated as a non-business delta, but this can be changed in two different
ways.
The first way to make a delta be business is to pass in the 2nd argument to
the function. The $business argument may be a string 'standard' or
'business' to explicitly set the type of delta. Alternately, any non-zero
value for $business will force the delta to be a business delta.
So the following are identical:
$delta->parse($string,'business');
$delta->parse($string,1);
and the following are identical:
$delta->parse($string);
$delta->parse($string,'standard');
$delta->parse($string,0);
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 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 equivalent:
in 4 hours business
4:0:0 business
business 0:0:0:0:4:0:0
There are also words "exact" or "approximate" which may
be included in the delta for backward compatibility. However, they will be
ignored. The accuracy of delta (exact, semi-exact, approximate) will be
determined only by what fields are present in the delta.
When a delta is parsed, it is automatically normalized, unless the
$no_normalize argument is passed in. It can be the string 'nonormalize' or
any non-zero value. If passing it as a non-zero value, the $business
argument MUST be included (though it can be zero) in order to avoid
ambiguity.
So the following are equivalent:
$delta->parse($string,'nonormalize');
$delta->parse($string,$business,1);
- input
-
$str = $delta->input();
This returns the string that was parsed to form the delta.
- set
-
$err = $delta->set($field,$val [,$no_normalize]);
This explicitly sets one or more fields in a delta.
$field can be any of the following:
$field $val
delta [Y,M,W,D,H,MN,S] sets the entire delta
business [Y,M,W,D,H,MN,S] sets the entire delta
standard [Y,M,W,D,H,MN,S] sets the entire delta
y YEAR sets one field
M MONTH
w WEEK
d DAY
h HOUR
m MINUTE
s SECOND
mode business, standard
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. Also, when setting the entire delta, signs are not
carried from one field to another.
By default, a delta is normalized, but passing $no_normalize as any true
value, this will not be done.
If $no_normalize is not passed in, the current value for the delta (which
defaults to 0) will be used.
For backwards compatibility, 'normal' can be used in place of 'standard',
both as $field or as $val.
- printf
-
$out = $delta->printf($in);
@out = $delta->printf(@in);
This takes a string or list of strings 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.
- calc
-
$date2 = $delta->calc($date1 [,$subtract]);
$delta3 = $delta1->calc($delta2 [,$subtract]);
Please refer to the Date::Manip::Calc documentation for details.
- type
-
$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
standard : returns 1 if it is a standard (non-business delta)
exact : returns 1 if it is exact
semi : returns 1 if it is semi-exact
approx : returns 1 if it is approximate
- value
-
$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 of fields.
undef is returned if there is no valid delta stored in $delta.
PRINTF DIRECTIVES¶
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.
- Simple directives
- These are directives which print simple characters.
Currently, the only one is:
%% Replaced by a single '%'
As an example:
$delta->printf('|%%|');
=> |%|
- 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
$delta->printf('|Month: %Mv|');
=> |Month: 2|
$delta->printf('|Day: %+05dv|');
=> |Day: +0004|
$delta->printf('|Day: %+<5dv|');
=> |Day: +4|
$delta->printf('|Day: %>5sv|');
=> |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:
%sdh
Any time all of X, Y, and Z are from a single set of fields, exact
relationships are used.
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 part and a semi-approximate relationship
is needed to link the W/D part with the H/MN/S part. These relationships
are:
1 day = 24 hours
1 year = 365.2425
For business deltas, the approximate and semi-approximate relationships used
to link the fields together are:
1 week = X (length of business week in days)
1 year = X/7 * 365.2425
For business deltas, the length of the day is defined using WorkDayStart and
WorkDayEnd. For non-business deltas, a day is 24 hours long (i.e. daylight
saving time is ignored).
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
$delta->printf('|%.4Myw|');
=> |14.6900|
1 year, 2 months, 3 weeks is approximately
14.6900 months
- 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 sign.
$delta->printf('|%Dt|');
=> |+1:2:+3:+4:5:6:7|
$delta->printf('|%+Dyd|');
=> |+1:+2:+3:+4|
KNOWN BUGS¶
None known.
BUGS AND QUESTIONS¶
Please refer to the Date::Manip::Problems documentation for information on
submitting bug reports or questions to the author.
SEE ALSO¶
Date::Manip - main module documentation
LICENSE¶
This script is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
AUTHOR¶
Sullivan Beck (sbeck@cpan.org)