# Copyright (c) 2008-2017 Sullivan Beck. All rights reserved.

# This program is free software; you can redistribute it and/or modify it

# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Changes5to6 - describes differences between 5.xx and 6.00

=head1 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.

=head1 OVERVIEW

The Date::Manip 5.xx series of suffered from several weaknesses. These

included:

=over 4

=item B<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.

=item B<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.

=item B<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.

=item B<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.

=back

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.

=head1 GENERAL CHANGES

=over 4

=item B<(*) 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.

=item B<(*) 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.

=item B<(*) 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.

=item B<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.

=back

=head1 TIME ZONE SUPPORT

=over 4

=item B<(*) 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.

=item B<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.

=item B<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

=item B

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.

=item B<(*) 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.

=back

=head1 CONFIG FILES AND VARIABLES

=over 4

=item B<(*) 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")

=item B<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.

=item B<(*) 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")

=item B<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

   IntCharSet      This has been replaced with better support for

                   international character sets. The Encoding config

                   variable may be used instead.

=item B<Other config variables deprecated>

The following config variables are deprecated and will be removed

in some future version:

   TZ              Use SetDate or ForceDate instead.

=item B<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.

=item B<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).

=back

=head1 DATE PARSING AND OPERATIONS

=over 4

=item B<(*) 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.

=item B<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.

=item B<(*) 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.

=item B<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.

=item B<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.

=item B<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.xx, 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.

=item B<(*) 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.

=item B<%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

=back

=head1 DELTAS

=over 4

=item B<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.

=item B<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.00, 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.

=item B<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.

=item B<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::DM5 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.

=back

=head1 RECURRENCES

=over 4

=item B<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 occurrence of the 4th day of the week in February.

The meaning has been changed to refer to the 3rd occurrence 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.

=item B<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.

=item B<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]

=item B<Other minor recurrence changes>

Previously, ParseRecur would supply default dates if the start or

end were missing. This is no longer done.

=back

=head1 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:

=over 4

=item B<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.

=item B<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.

=back

=head1 BUGS AND QUESTIONS

Please refer to the L<Date::Manip::Problems> documentation for

information on submitting bug reports or questions to the author.

=head1 SEE ALSO

L<Date::Manip>       - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or

modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut