NAME¶
Date::Manip::Changes5to6 - describes differences between 5.xx and 6.00
SYNOPSIS¶
Date::Manip 6.00 represents a complete rethink and rewrite of Date::Manip. A
great deal of effort was made to make sure that 6.00 is almost backwards
compatible with 5.xx whenever feasible, but some functionality has changed in
backwards incompatible ways. Other parts have been deprecated and will be
removed at some point in the future.
This document describes the differences between the 5.xx series and version
6.00. This page primarily describes technical details, most of which do not
impact how Date::Manip is used in scripts. If you want to make sure that a
script which ran with 5.xx will run with 6.xx, refer to the
Date::Manip::Migration5to6 document.
OVERVIEW¶
The Date::Manip 5.xx series of suffered from several weaknesses. These included:
- Poor time zone support
- Time zone support in 5.xx was broken. Determining a time
zone, and understanding daylight saving time changes was incomplete (at
best) and totally inadequate to do true timezone operations.
- Parsing too complicated and unstructured
- The parsing routines had grown very complicated, and overly
permissive over time and were in need of a complete overhaul.
- Lacking OO model
- Date::Manip 5.xx was written as a functional module, not an
OO module, but date handling would lend itself very well to being OO with
different classes to handle dates, deltas, and recurrences.
The OO model allows a lot of information to be stored with each date (such
as time zone information) which is discarded in the functional
interface.
- Too monolithic
- The entire Date::Manip module was contained in one huge
file. Breaking up the module would make it much easier to deal with.
Date::Manip 6.00 is a complete rewrite of Date::Manip to address these and other
issues.
The following sections address how Date::Manip 6.00 differs from previous
releases, and describes changes that might need to be made to your script in
order to upgrade from 5.xx to 6.00.
The most important changes are marked with asterisks.
GENERAL CHANGES¶
- (*) Requires perl 5.10.0
- Please see the Date::Manip::Problems document for a
discussion of this problem. It's in the KNOWN COMPLAINTS section.
- (*) Breaking into smaller modules
- Date::Manip module has been broken up from one huge module
into a large number of smaller more manageable modules. The main
Date::Manip module is still present, and contains all of the functions
from Date::Manip 5.xx (except that they now call functions from all the
other modules to do the actual work). In general, the Date::Manip module
from 6.00 is backwards compatible.
A number of new modules have been created as well. These can be used
directly, bypassing the main Date::Manip module. These include the
following:
Date::Manip::Base contains many basic date operations which may be used to
do simple date manipulation tasks without all the overhead of the full
Date::Manip module.
Date::Manip::TZ contains time zone operations.
Handling dates, deltas, and recurrences are now done in Date::Manip::Date,
Date::Manip::Delta, and Date::Manip::Recur.
All of these modules are object oriented, and are designed to be used
directly, so if you prefer an OO interface over a functional interface,
use these modules.
- (*) Intermediate data cached
- In order to improve the performance of Date::Manip, many
intermediate values are cached. This does impact the memory footprint of
the module, but it has a huge impact on the performance of the module.
Some types of data depend on the config variables used, and these are cached
separately, and this cache is automatically cleared every time a config
variable is set. As a result, it is best if you set all config variables
at the start, and then leave them alone completely to get optimal use of
cached data.
A side effect of all this is that the Memoize module should not be used in
conjunction with Date::Manip.
In the version 5.xx documentation, it was mentioned that the Memoize module
might be used to improve performance in some cases. This is no longer the
case. It should not be used with Date::Manip, even if you use the
functional interface instead of the OO interface.
- Taint safe
- Date::Manip now contains no tainted data, and should run
without problems with taint checking on provided you do not set additional
methods for determining the system time zone using the curr_zone_methods
function.
Ideally, this should never be necessary. If it is necessary, I'd like to
hear about it so that I can add whatever standard methods are needed to
the built in list.
TIME ZONE SUPPORT¶
- (*) Complete handling of time zones
- The biggest problem with Date::Manip 5.xx was it's
inability to correctly handle time zones and Daylight Saving Time. That is
now fixed. Version 6.00 includes support for every time zone included in
the zoneinfo (aka Olson) database which includes the definitions of
(hopefully) all of the time zones used in the world.
- Individual time zones will no longer be added
- Prior to 5.55, time zones were added upon request. Since
6.00 now supports a full set of standard time zones, I will no longer add
in individual time zones (Date::Manip::TZ includes functionality for
adding them yourself if they are needed). With Date::Manip now having full
time zone support, I'm not interested in supporting my own time zone
database.
However, I am interested in adding sets of time zones from various
"standards".
Date::Manip 6.00 includes time zones from the following standards:
Olson zoneinfo database
all Microsoft Windows time zones
zones listed in RFC-822
If there are additional standards that include additional time zones not
included here, please point me to them so they can be added. This could
include published lists of time zone names supported on some operating
system which have different names than the zoneinfo list.
- Nonstandard time zone abbreviations removed
- Some of the individual standards that were added in the
5.xx series are not included in any of the standards listed above.
As of 6.00, only time zones from standards will be included in the
distribution (others can be added by users using the functions described
in Date::Manip::TZ to add aliases for existing time zones).
The following time zones were in Date::Manip 5.xx but not in 6.00.
IDLW -1200 International Date Line West
NT -1100 Nome
SAT -0400 Chile
CLDT -0300 Chile Daylight
AT -0200 Azores
MEWT +0100 Middle European Winter
MEZ +0100 Middle European
FWT +0100 French Winter
GB +0100 GMT with daylight saving
SWT +0100 Swedish Winter
MESZ +0200 Middle European Summer
FST +0200 French Summer
METDST +0200 An alias for MEST used by HP-UX
EETDST +0300 An alias for eest used by HP-UX
EETEDT +0300 Eastern Europe, USSR Zone 1
BT +0300 Baghdad, USSR Zone 2
IT +0330 Iran
ZP4 +0400 USSR Zone 3
ZP5 +0500 USSR Zone 4
IST +0530 Indian Standard
ZP6 +0600 USSR Zone 5
AWST +0800 Australian Western Standard
ROK +0900 Republic of Korea
AEST +1000 Australian Eastern Standard
ACDT +1030 Australian Central Daylight
CADT +1030 Central Australian Daylight
AEDT +1100 Australian Eastern Daylight
EADT +1100 Eastern Australian Daylight
NZT +1200 New Zealand
IDLE +1200 International Date Line East
- A lot of support modules and files
- Date::Manip now includes a large number of files and
modules that are used to support time zones.
A series of modules are included which are auto-generated from the zoneinfo
database. The Date::Manip::Zones, Date::Manip::TZ::*, and
Date::Manip::Offset::* modules are all automatically generated and are not
intended to be used directly. Instead, the Date::Manip::TZ module is used
to access the data stored there.
A separate time zone module (Date::Manip::TZ::*) is included for every
single time zone. There is also a module (Date::Manip::Offset::*) for
every different offset. All told, there are almost 1000 modules. These are
included to make time zone handling more efficient. Rather than
calculating everything on the fly, information about each time zone and
offset are included here which greatly speeds up the handling of time
zones. These modules are only loaded as needed (i.e. only the modules
related to the specific time zones you refer to are ever loaded), so there
is no performance penalty to having them.
Also included in the distribution are a script (tzdata) and additional
module (Date::Manip::TZdata). These are used to automatically generate the
time zone modules, and are of no use to anyone other than the maintainer
of Date::Manip. They are included solely for the sake of completeness. If
someone wanted to fork Date::Manip, all the tools necessary to do so are
included in the distribution.
- (*) Meaning of $::TZ and
$ENV {TZ}
- In Date::Manip 5.x, you could specify what time zone you
wanted to work in using either the $::TZ or $ENV{TZ} variables.
Date::Manip 6.00 makes use of two different time zones: the actual local
time zone the computer is running in (and which is used by the system
clock), and a time zone that you want to work in. Typically, these are the
same, but they do not have to be.
As of Date::Manip 6.00, the $::TZ and $ENV{TZ} variables are used only to
specify the actual local time zone.
In order to specify an alternate time zone to work in, use the SetDate or
ForceDate config variables.
CONFIG FILES AND VARIABLES¶
- (*) Date_Init handling of config variables
- The handling of config variables has changed slightly.
Previously, variables passed in to Date_Init overrode values from config
files. This has changed slightly. Options to Date_Init are now parsed in
the order they are listed, so the following:
Date_Init("DateFormat=Other","ConfigFile=DateManip.cnf")
would first set the DateFormat variable, and then it would read the config
file "DateManip.cnf". If that config file included a DateFormat
definition, it would override the one passed in to Date_Init.
The proper way to override config files is to pass the config files in
first, followed by any script-specific overrides. In other words:
Date_Init("ConfigFile=DateManip.cnf","DateFormat=Other")
- Date_Init doesn't return the config variables
- In Date::Manip::5.xx, Date_Init could return the list of
all config variables. This functionality is no longer supported. Date_Init
is used strictly to set config variables.
- (*) Config file options
- Date::Manip 5.xx had the concept of a global and personal
config file. In addition, the personal config file could be looked for in
a path of directories. All this was specified using the config variables:
GlobalCnf
IgnoreGlobalCnf
PersonalCnf
PersonalCnfPath
PathSep
All of these have been removed. Instead, the single config variable:
ConfigFile
will be used to specify config files (with no distinction between a global
and personal config file). Also, no path searching is done. Each must be
specified by a complete path. Finally, any number of config files can be
used. So the following is valid:
Date_Init("ConfigFile=./Manip.cnf","ConfigFile=/tmp/Manip.cnf")
- Other config variables removed
- The following config variables have been removed.
TodayIsMidnight Use DefaultTime instead.
ConvTZ Use SetDate or ForceDate instead.
Internal Use Printable instead.
DeltaSigns Use the Date::Manip::Delta::printf
method to print deltas
UpdateCurrTZ With real time zone handling in
place, this is no longer necessary
- Other config variables deprecated
- The following config variables are deprecated and will be
removed in some future version:
TZ Use SetDate or ForceDate instead.
IntCharSet This has been replaced with better support for
international character sets. The Encoding config
variable may be used.
- Holidays
- Previously, holidays could be defined as a "Date +
Delta" or "Date - Delta" string. These predate recurrences,
and introduce some complexity into the handling of holidays. Since
recurrences are a much better way to define holidays, the "Date +
Delta" and "Date - Delta" strings are no longer
supported.
- TZ replaced (and enhanced)
- The SetDate and ForceDate variables (which include the
functionality of the deprecated TZ variable) are much improved as
described in the Date::Manip::Config documentation.
Since it is now handles time change correctly (allowing time changes to
occur in the alternate time zone), parsed results may be different than in
5.x (but since 5.x didn't have proper time zone handling, this is a good
thing).
DATE PARSING AND OPERATIONS¶
- (*) today, tomorrow, yesterday
- The words "today", "tomorrow", and
"yesterday" in 5.xx referred to the time now, 24 hours in the
future, and 24 hours in the past respectively.
As of 6.00, these are treated strictly as date strings, so they are the
current day, the day before, or the day after at the time 00:00:00.
The string "now" still refers to the current date and time.
- ISO 8601 formats
- A couple of the date formats from Date::Manip 5.xx
conflicted with ISO 8601 formats in the spec. These are documented in the
Date::Manip::Date documentation.
Dates are now parsed according to the spec (though a couple extensions have
been made, which are also documented in the Date::Manip::Date
documentation).
There is one change with respect to Date::Manip 5.xx that results from a
possible misinterpretation of the standard. In Date::Manip, there is a
small amount of ambiguity in how the Www-D date formats are understood.
The date:
1996-w02-3
might be interpreted in two different ways. It could be interpreted as
Wednesday (day 3) of the 2nd week of 1996, or as the 3rd day of the 2nd
week of 1996 (which would be Tuesday if the week begins on Sunday). Since
the specification only works with weeks which begin on day 1, the two are
always equivalent in the specification, and the language of the
specification doesn't clearly indicate one interpretation over the other.
Since Date::Manip supports the concept of weeks starting on days other than
day 1 (Monday), the two interpretations are not equivalent.
In Date::Manip 5.xx, the date was interpreted as Wednesday of the 2nd week,
but I now believe that the other interpretation (3rd day of the week) is
the interpretation intended by the specification. In addition, if this
interpretation is used, it is easy to get the other interpretation.
If 1996-w02-3 means the 3rd day of the 2nd week, then to get Wednesday (day
3) of the week, use the following two Date::Manip::Date methods:
$err = $date->parse("1996-w02-1");
$date2 = $date->next(3,1);
The first call gets the 1st day of the 2nd week, and the second call gets
the next Wednesday.
If 1996-w02-3 is interpreted as Wednesday of the 2nd week, then to get the
3rd day of the week involves significantly more work.
In Date::Manip 6.00, the date will now be parsed as the 3rd day of the 2nd
week.
- (*) Parsing is now more rigid
- The philosophy in Date::Manip 5.xx with respect to parsing
dates was "if there's any conceivable way to find a valid date in the
string, do so". As a result, strings which did not look like they
could contain a valid date often would.
This manifested itself it two ways. First, a lot of punctuation was ignored.
For example, the string "01 // 03 -. 75" was the date
1975-01-03.
Second, a lot of word breaks were optional and it was often acceptable to
run strings together. For example, the delta "in5seconds" would
have worked.
With Date::Manip 6.00, parsing now tries to find a valid date in the string,
but uses a more rigidly defined set of allowed formats which should more
closely match how the dates would actually be expressed in real life. The
punctuation allowed is more rigidly defined, and word breaks are required.
So "01/03/75" will work, but "01//03/75" and
"01/03-75" won't. Also, "in5seconds" will no longer
work, though "in 5 seconds" will work.
These changes serve to simplify some of the regular expressions used in
parsing dates, as well as simplifying the parsing routines. They also help
to recognize actually dates as opposed to typos... it was too easy to pass
in garbage and get a date out.
- Support dropped for a few formats
- I've dropped support for a few very uncommon (probably
never used) formats. These include (with Jan 3, 2009 as an example):
DD/YYmmm 03/09Jan
DD/YYYYmmm 03/2009Jan
mmmYYYY/DD Jan2009/03
YYYY/DDmmm 2009/03Jan
mmmYYYY Jan2009
YYYYmmm 2009Jan
The last two are no longer supported since they are incomplete.
With the exception of the incomplete forms, these could be added back in
with very little effort. If there is ever a request to do so, I probably
will.
- No longer parses the Apache format
- Date::Manip 5.xx supported the format:
DD/mmm/YYYY:HH:MN:SS
used in the apache logs. Due to the stricter parsing, this format is no
longer supported directly. However, the parse_format method may be used to
parse the date directly from an apache log line with no need to extract
the date string beforehand.
- Date_PrevWorkDay behavior
- The behavior of Date_PrevWorkDay has changed slightly.
The starting date is checked. If $timecheck was non-zero, the check failed
if the date was not a business date, or if the time was not during
business hours. If $timecheck was zero, the check failed if the date was
not a business date, but the time was ignored.
In 5.xx, if the check failed, and $timecheck was non-zero, day 0 was defined
as the start of the next business day, but if $timecheck was zero, day 0
was defined as the previous business day at the same time.
In 6.x, if the check fails, and $timecheck is non-zero, the behavior is the
same as before. If $timecheck is zero, day 0 is defined as the next
business day at the same time.
So day 0 is now always the same, where before, day 0 meant two different
things depending on whether $timecheck was zero or not.
- (*) Default time
- In Date::Manip 5.xx, the default times for dates was
handled in an inconsistent manner. In the Date::Manip::Date documentation,
if you parse a date from the "Common date formats" section, in
Date::Manip 5.xx, if no time was included, it defaulted to
"00:00:00". If you parsed a date from the "Less common
formats" section, the default time was the current time.
So running a program on Jun 5, 2009 at noon that parsed the following dates
gave the following return values:
Jun 12 => Jun 12, 2009 at 00:00:00
next week => Jun 12, 2009 at 12:00:00
This behavior is changed and now relies on the config variable DefaultTime.
If DefaultTime is "curr", the default time for any date which
includes no information about the time is the current time. Otherwise, the
default time is midnight.
- %z format
- In Date::Manip 5.xx, the %z format would give an offset in
the form: -0500. Now it gives it in the form: -05:00:00
DELTAS¶
- Dropped mixed style delta parsing
- In Date::Manip 5.xx, a parsed delta could be written in the
delta style
1:2:3
or in a language-specific expanded form:
1 hour 2 minutes 3 seconds
or in a mixed form:
1 hour 2:3
The mixed form has been dropped since I doubt that it sees much use in real
life, and by dropping the mixed form, the parsing is much simpler.
- Approximate date/date calculations
- In Date::Manip 5.xx, the approximate delta between the two
dates:
Jan 10 1996 noon
Jan 7 1998 noon
was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). As of Date::Manip 6.0,
the delta is +2:0:-0:3:0:0:0 (or 2 years minus 3 days). Although this
leads to mixed-sign deltas, it is actually how more people would think
about the delta. It has the additional advantage of being MUCH easier and
faster to calculate.
- Approximate relationships in deltas
- When printing parts of deltas in Date::Manip::5.xx, the
approximate relationship of 1 year = 365.25 days was used. This is the
correct value for the Julian calendar, but for the Gregorian calendar, a
better value is 365.2425, and this is used in version 6.00.
- Old style formats
- The formats used in the printf command are slightly
different than in the old Delta_Format command.
The old formats are described in the Date::Manip manual, and the new ones
are in the Date::Manip::Delta manual.
The new formats are much more flexible and I encourage you to switch over,
however at this point, the old style formats are officially supported for
the Delta_Format command.
At some point, the old style formats may be deprecated (and removed at some
point beyond that), but for now, they are not.
The old formats are NOT available using the printf method.
RECURRENCES¶
- The day field meaning changed in a few
recurrences
- The value of the day field can refer to several different
things including the day of week number (Monday=1 to Sunday=7), day of
month (1-31), day of year (1-366), etc.
In Date::Manip 5.xx, it could also refer to the nth day of the week (i.e. 1
being the 1st day of the week, -1 being the last day of the week). This
meaning is no longer used in 6.xx.
For example, the recurrence:
1*2:3:4:0:0:0
referred to the 3rd occurence of the 4th day of the week in February.
The meaning has been changed to refer to the 3rd occurence of day 4
(Thursday) in February. This is a much more useful type of recurrence.
As a result of this change, the related recurrence:
1*2:3:-1:0:0:0
is invalid. Negative numbers may be used to refer to the nth day of the
week, but NOT when referring to the day of week numbers.
- Recurrence range now inclusive
- Previously, the list of dates implied by the recurrence
were on or after the start date, but before the end date.
This has been changed so that the dates may be on or before the end
date.
- Dropped support for a couple English
recurrences
- Date::Manip 5.xx claimed support for a recurrence:
every 2nd day in June [1997]
In actuality, this recurrence is not practical to calculate. It requires a
base date which might imply June 1,3,5,... in 1997 but June 2,4,6 in 1998.
In addition, the recurrence does not fit the mold for other recurrences that
are an approximate distance apart. This type of recurrence has a number of
closely spaced events with 11-month gaps between groups.
I no longer consider this a valid recurrence and support is now dropped for
this string.
I also dropped the following for a similar reason:
every 6th tuesday [in 1999]
- Other minor recurrence changes
- Previously, ParseRecur would supply default dates if the
start or end were missing. This is no longer done.
DATE::MANIP FUNCTIONS¶
The Date::Manip module contains the same functions that Date::Manip 5.xx had
(though the OO modules do all the work now). In general, the routines behave
the same as before with the following exceptions:
- Date_ConvTZ
- Previously, Date_ConvTZ took 1 to 4 arguments and used the
local time zone and the ConvTZ config variable to fill in missing
arguments.
Now, the Date_ConvTZ function only supports a 3 argument call:
$date = Date_ConvTZ($date,$from,$to);
If $from is not given, it defaults to the local time zone. If $to is not
given, it defaults to the local time zone.
The optional 4th argument ($errlevel) is no longer supported. If there is an
error, an empty string is returned.
- DateCalc
- In Date::Manip 5.xx, it was recommended that you pass
arguments to ParseDate or ParseDateDelta. This is not recommended with
6.00 since it is much more intelligent about handling the arguments, and
you'll just end up parsing the date/delta twice.
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)