1Date::Manip::Changes5toU6s(e3r)Contributed Perl DocumentDaattieo:n:Manip::Changes5to6(3)
2
3
4

NAME

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

SYNOPSIS

9       Date::Manip 6.00 represents a complete rethink and rewrite of
10       Date::Manip.  A great deal of effort was made to make sure that 6.00 is
11       almost backwards compatible with 5.xx whenever feasible, but some
12       functionality has changed in backwards incompatible ways. Other parts
13       have been deprecated and will be removed at some point in the future.
14
15       This document describes the differences between the 5.xx series and
16       version 6.00. This page primarily describes technical details, most of
17       which do not impact how Date::Manip is used in scripts. If you want to
18       make sure that a script which ran with 5.xx will run with 6.xx, refer
19       to the Date::Manip::Migration5to6 document.
20

OVERVIEW

22       The Date::Manip 5.xx series of suffered from several weaknesses. These
23       included:
24
25       Poor time zone support
26           Time zone support in 5.xx was broken. Determining a time zone, and
27           understanding daylight saving time changes was incomplete (at best)
28           and totally inadequate to do true timezone operations.
29
30       Parsing too complicated and unstructured
31           The parsing routines had grown very complicated, and overly
32           permissive over time and were in need of a complete overhaul.
33
34       Lacking OO model
35           Date::Manip 5.xx was written as a functional module, not an OO
36           module, but date handling would lend itself very well to being OO
37           with different classes to handle dates, deltas, and recurrences.
38
39           The OO model allows a lot of information to be stored with each
40           date (such as time zone information) which is discarded in the
41           functional interface.
42
43       Too monolithic
44           The entire Date::Manip module was contained in one huge file.
45           Breaking up the module would make it much easier to deal with.
46
47       Date::Manip 6.00 is a complete rewrite of Date::Manip to address these
48       and other issues.
49
50       The following sections address how Date::Manip 6.00 differs from
51       previous releases, and describes changes that might need to be made to
52       your script in order to upgrade from 5.xx to 6.00.
53
54       The most important changes are marked with asterisks.
55

GENERAL CHANGES

57       (*) Requires perl 5.10.0
58           Please see the Date::Manip::Problems document for a discussion of
59           this problem. It's in the KNOWN COMPLAINTS section.
60
61       (*) Breaking into smaller modules
62           Date::Manip module has been broken up from one huge module into a
63           large number of smaller more manageable modules. The main
64           Date::Manip module is still present, and contains all of the
65           functions from Date::Manip 5.xx (except that they now call
66           functions from all the other modules to do the actual work). In
67           general, the Date::Manip module from 6.00 is backwards compatible.
68
69           A number of new modules have been created as well. These can be
70           used directly, bypassing the main Date::Manip module. These include
71           the following:
72
73           Date::Manip::Base contains many basic date operations which may be
74           used to do simple date manipulation tasks without all the overhead
75           of the full Date::Manip module.
76
77           Date::Manip::TZ contains time zone operations.
78
79           Handling dates, deltas, and recurrences are now done in
80           Date::Manip::Date, Date::Manip::Delta, and Date::Manip::Recur.
81
82           All of these modules are object oriented, and are designed to be
83           used directly, so if you prefer an OO interface over a functional
84           interface, use these modules.
85
86       (*) Intermediate data cached
87           In order to improve the performance of Date::Manip, many
88           intermediate values are cached. This does impact the memory
89           footprint of the module, but it has a huge impact on the
90           performance of the module.
91
92           Some types of data depend on the config variables used, and these
93           are cached separately, and this cache is automatically cleared
94           every time a config variable is set. As a result, it is best if you
95           set all config variables at the start, and then leave them alone
96           completely to get optimal use of cached data.
97
98           A side effect of all this is that the Memoize module should not be
99           used in conjunction with Date::Manip.
100
101           In the version 5.xx documentation, it was mentioned that the
102           Memoize module might be used to improve performance in some cases.
103           This is no longer the case. It should not be used with Date::Manip,
104           even if you use the functional interface instead of the OO
105           interface.
106
107       Taint safe
108           Date::Manip now contains no tainted data, and should run without
109           problems with taint checking on provided you do not set additional
110           methods for determining the system time zone using the
111           curr_zone_methods function.
112
113           Ideally, this should never be necessary. If it is necessary, I'd
114           like to hear about it so that I can add whatever standard methods
115           are needed to the built in list.
116

TIME ZONE SUPPORT

118       (*) Complete handling of time zones
119           The biggest problem with Date::Manip 5.xx was it's inability to
120           correctly handle time zones and Daylight Saving Time. That is now
121           fixed. Version 6.00 includes support for every time zone included
122           in the zoneinfo (aka Olson) database which includes the definitions
123           of (hopefully) all of the time zones used in the world.
124
125       Individual time zones will no longer be added
126           Prior to 5.55, time zones were added upon request. Since 6.00 now
127           supports a full set of standard time zones, I will no longer add in
128           individual time zones (Date::Manip::TZ includes functionality for
129           adding them yourself if they are needed).  With Date::Manip now
130           having full time zone support, I'm not interested in supporting my
131           own time zone database.
132
133           However, I am interested in adding sets of time zones from various
134           "standards".
135
136           Date::Manip 6.00 includes time zones from the following standards:
137
138              Olson zoneinfo database
139              all Microsoft Windows time zones
140              zones listed in RFC-822
141
142           If there are additional standards that include additional time
143           zones not included here, please point me to them so they can be
144           added.  This could include published lists of time zone names
145           supported on some operating system which have different names than
146           the zoneinfo list.
147
148       Nonstandard time zone abbreviations removed
149           Some of the individual standards that were added in the 5.xx series
150           are not included in any of the standards listed above.
151
152           As of 6.00, only time zones from standards will be included in the
153           distribution (others can be added by users using the functions
154           described in Date::Manip::TZ to add aliases for existing time
155           zones).
156
157           The following time zones were in Date::Manip 5.xx but not in 6.00.
158
159              IDLW    -1200    International Date Line West
160              NT      -1100    Nome
161              SAT     -0400    Chile
162              CLDT    -0300    Chile Daylight
163              AT      -0200    Azores
164              MEWT    +0100    Middle European Winter
165              MEZ     +0100    Middle European
166              FWT     +0100    French Winter
167              GB      +0100    GMT with daylight saving
168              SWT     +0100    Swedish Winter
169              MESZ    +0200    Middle European Summer
170              FST     +0200    French Summer
171              METDST  +0200    An alias for MEST used by HP-UX
172              EETDST  +0300    An alias for eest used by HP-UX
173              EETEDT  +0300    Eastern Europe, USSR Zone 1
174              BT      +0300    Baghdad, USSR Zone 2
175              IT      +0330    Iran
176              ZP4     +0400    USSR Zone 3
177              ZP5     +0500    USSR Zone 4
178              IST     +0530    Indian Standard
179              ZP6     +0600    USSR Zone 5
180              AWST    +0800    Australian Western Standard
181              ROK     +0900    Republic of Korea
182              AEST    +1000    Australian Eastern Standard
183              ACDT    +1030    Australian Central Daylight
184              CADT    +1030    Central Australian Daylight
185              AEDT    +1100    Australian Eastern Daylight
186              EADT    +1100    Eastern Australian Daylight
187              NZT     +1200    New Zealand
188              IDLE    +1200    International Date Line East
189
190       A lot of support modules and files
191           Date::Manip now includes a large number of files and modules that
192           are used to support time zones.
193
194           A series of modules are included which are auto-generated from the
195           zoneinfo database.  The Date::Manip::Zones, Date::Manip::TZ::*, and
196           Date::Manip::Offset::* modules are all automatically generated and
197           are not intended to be used directly. Instead, the Date::Manip::TZ
198           module is used to access the data stored there.
199
200           A separate time zone module (Date::Manip::TZ::*) is included for
201           every single time zone. There is also a module
202           (Date::Manip::Offset::*) for every different offset. All told,
203           there are almost 1000 modules.  These are included to make time
204           zone handling more efficient. Rather than calculating everything on
205           the fly, information about each time zone and offset are included
206           here which greatly speeds up the handling of time zones. These
207           modules are only loaded as needed (i.e. only the modules related to
208           the specific time zones you refer to are ever loaded), so there is
209           no performance penalty to having them.
210
211           Also included in the distribution are a script (tzdata) and
212           additional module (Date::Manip::TZdata). These are used to
213           automatically generate the time zone modules, and are of no use to
214           anyone other than the maintainer of Date::Manip. They are included
215           solely for the sake of completeness. If someone wanted to fork
216           Date::Manip, all the tools necessary to do so are included in the
217           distribution.
218
219       (*) Meaning of $::TZ and $ENV{TZ}
220           In Date::Manip 5.x, you could specify what time zone you wanted to
221           work in using either the $::TZ or $ENV{TZ} variables.
222
223           Date::Manip 6.00 makes use of two different time zones: the actual
224           local time zone the computer is running in (and which is used by
225           the system clock), and a time zone that you want to work in.
226           Typically, these are the same, but they do not have to be.
227
228           As of Date::Manip 6.00, the $::TZ and $ENV{TZ} variables are used
229           only to specify the actual local time zone.
230
231           In order to specify an alternate time zone to work in, use the
232           SetDate or ForceDate config variables.
233

CONFIG FILES AND VARIABLES

235       (*) Date_Init handling of config variables
236           The handling of config variables has changed slightly.
237
238           Previously, variables passed in to Date_Init overrode values from
239           config files. This has changed slightly. Options to Date_Init are
240           now parsed in the order they are listed, so the following:
241
242              Date_Init("DateFormat=Other","ConfigFile=DateManip.cnf")
243
244           would first set the DateFormat variable, and then it would read the
245           config file "DateManip.cnf". If that config file included a
246           DateFormat definition, it would override the one passed in to
247           Date_Init.
248
249           The proper way to override config files is to pass the config files
250           in first, followed by any script-specific overrides. In other
251           words:
252
253              Date_Init("ConfigFile=DateManip.cnf","DateFormat=Other")
254
255       Date_Init doesn't return the config variables
256           In Date::Manip::5.xx, Date_Init could return the list of all config
257           variables. This functionality is no longer supported.  Date_Init is
258           used strictly to set config variables.
259
260       (*) Config file options
261           Date::Manip 5.xx had the concept of a global and personal config
262           file. In addition, the personal config file could be looked for in
263           a path of directories. All this was specified using the config
264           variables:
265
266              GlobalCnf
267              IgnoreGlobalCnf
268              PersonalCnf
269              PersonalCnfPath
270              PathSep
271
272           All of these have been removed. Instead, the single config
273           variable:
274
275              ConfigFile
276
277           will be used to specify config files (with no distinction between a
278           global and personal config file). Also, no path searching is done.
279           Each must be specified by a complete path. Finally, any number of
280           config files can be used. So the following is valid:
281
282              Date_Init("ConfigFile=./Manip.cnf","ConfigFile=/tmp/Manip.cnf")
283
284       Other config variables removed
285           The following config variables have been removed.
286
287              TodayIsMidnight  Use DefaultTime instead.
288
289              ConvTZ           Use SetDate or ForceDate instead.
290
291              Internal         Use Printable instead.
292
293              DeltaSigns       Use the Date::Manip::Delta::printf
294                               method to print deltas
295
296              UpdateCurrTZ     With real time zone handling in
297                               place, this is no longer necessary
298
299              IntCharSet      This has been replaced with better support for
300                              international character sets. The Encoding config
301                              variable may be used instead.
302
303       Other config variables deprecated
304           The following config variables are deprecated and will be removed
305           in some future version:
306
307              TZ              Use SetDate or ForceDate instead.
308
309       Holidays
310           Previously, holidays could be defined as a "Date + Delta" or "Date
311           - Delta" string. These predate recurrences, and introduce some
312           complexity into the handling of holidays. Since recurrences are a
313           much better way to define holidays, the "Date + Delta" and "Date -
314           Delta" strings are no longer supported.
315
316       TZ replaced (and enhanced)
317           The SetDate and ForceDate variables (which include the
318           functionality of the deprecated TZ variable) are much improved as
319           described in the Date::Manip::Config documentation.
320
321           Since it is now handles time change correctly (allowing time
322           changes to occur in the alternate time zone), parsed results may be
323           different than in 5.x (but since 5.x didn't have proper time zone
324           handling, this is a good thing).
325

DATE PARSING AND OPERATIONS

327       (*) today, tomorrow, yesterday
328           The words "today", "tomorrow", and "yesterday" in 5.xx referred to
329           the time now, 24 hours in the future, and 24 hours in the past
330           respectively.
331
332           As of 6.00, these are treated strictly as date strings, so they are
333           the current day, the day before, or the day after at the time
334           00:00:00.
335
336           The string "now" still refers to the current date and time.
337
338       ISO 8601 formats
339           A couple of the date formats from Date::Manip 5.xx conflicted with
340           ISO 8601 formats in the spec. These are documented in the
341           Date::Manip::Date documentation.
342
343           Dates are now parsed according to the spec (though a couple
344           extensions have been made, which are also documented in the
345           Date::Manip::Date documentation).
346
347           There is one change with respect to Date::Manip 5.xx that results
348           from a possible misinterpretation of the standard. In Date::Manip,
349           there is a small amount of ambiguity in how the Www-D date formats
350           are understood.
351
352           The date:
353
354              1996-w02-3
355
356           might be interpreted in two different ways. It could be interpreted
357           as Wednesday (day 3) of the 2nd week of 1996, or as the 3rd day of
358           the 2nd week of 1996 (which would be Tuesday if the week begins on
359           Sunday). Since the specification only works with weeks which begin
360           on day 1, the two are always equivalent in the specification, and
361           the language of the specification doesn't clearly indicate one
362           interpretation over the other.
363
364           Since Date::Manip supports the concept of weeks starting on days
365           other than day 1 (Monday), the two interpretations are not
366           equivalent.
367
368           In Date::Manip 5.xx, the date was interpreted as Wednesday of the
369           2nd week, but I now believe that the other interpretation (3rd day
370           of the week) is the interpretation intended by the specification.
371           In addition, if this interpretation is used, it is easy to get the
372           other interpretation.
373
374           If 1996-w02-3 means the 3rd day of the 2nd week, then to get
375           Wednesday (day 3) of the week, use the following two
376           Date::Manip::Date methods:
377
378              $err   = $date->parse("1996-w02-1");
379              $date2 = $date->next(3,1);
380
381           The first call gets the 1st day of the 2nd week, and the second
382           call gets the next Wednesday.
383
384           If 1996-w02-3 is interpreted as Wednesday of the 2nd week, then to
385           get the 3rd day of the week involves significantly more work.
386
387           In Date::Manip 6.00, the date will now be parsed as the 3rd day of
388           the 2nd week.
389
390       (*) Parsing is now more rigid
391           The philosophy in Date::Manip 5.xx with respect to parsing dates
392           was "if there's any conceivable way to find a valid date in the
393           string, do so". As a result, strings which did not look like they
394           could contain a valid date often would.
395
396           This manifested itself it two ways. First, a lot of punctuation was
397           ignored. For example, the string "01 // 03 -. 75" was the date
398           1975-01-03.
399
400           Second, a lot of word breaks were optional and it was often
401           acceptable to run strings together. For example, the delta
402           "in5seconds" would have worked.
403
404           With Date::Manip 6.00, parsing now tries to find a valid date in
405           the string, but uses a more rigidly defined set of allowed formats
406           which should more closely match how the dates would actually be
407           expressed in real life.  The punctuation allowed is more rigidly
408           defined, and word breaks are required. So "01/03/75" will work, but
409           "01//03/75" and "01/03-75" won't. Also, "in5seconds" will no longer
410           work, though "in 5 seconds" will work.
411
412           These changes serve to simplify some of the regular expressions
413           used in parsing dates, as well as simplifying the parsing routines.
414           They also help to recognize actually dates as opposed to typos...
415           it was too easy to pass in garbage and get a date out.
416
417       Support dropped for a few formats
418           I've dropped support for a few very uncommon (probably never used)
419           formats. These include (with Jan 3, 2009 as an example):
420
421              DD/YYmmm      03/09Jan
422              DD/YYYYmmm    03/2009Jan
423              mmmYYYY/DD    Jan2009/03
424              YYYY/DDmmm    2009/03Jan
425
426              mmmYYYY       Jan2009
427              YYYYmmm       2009Jan
428
429           The last two are no longer supported since they are incomplete.
430
431           With the exception of the incomplete forms, these could be added
432           back in with very little effort. If there is ever a request to do
433           so, I probably will.
434
435       No longer parses the Apache format
436           Date::Manip 5.xx supported the format:
437
438              DD/mmm/YYYY:HH:MN:SS
439
440           used in the apache logs. Due to the stricter parsing, this format
441           is no longer supported directly. However, the parse_format method
442           may be used to parse the date directly from an apache log line with
443           no need to extract the date string beforehand.
444
445       Date_PrevWorkDay behavior
446           The behavior of Date_PrevWorkDay has changed slightly.
447
448           The starting date is checked. If $timecheck was non-zero, the check
449           failed if the date was not a business date, or if the time was not
450           during business hours. If $timecheck was zero, the check failed if
451           the date was not a business date, but the time was ignored.
452
453           In 5.xx, if the check failed, and $timecheck was non-zero, day 0
454           was defined as the start of the next business day, but if
455           $timecheck was zero, day 0 was defined as the previous business day
456           at the same time.
457
458           In 6.xx, if the check fails, and $timecheck is non-zero, the
459           behavior is the same as before. If $timecheck is zero, day 0 is
460           defined as the next business day at the same time.
461
462           So day 0 is now always the same, where before, day 0 meant two
463           different things depending on whether $timecheck was zero or not.
464
465       (*) Default time
466           In Date::Manip 5.xx, the default times for dates was handled in an
467           inconsistent manner.  In the Date::Manip::Date documentation, if
468           you parse a date from the "Common date formats" section, in
469           Date::Manip 5.xx, if no time was included, it defaulted to
470           "00:00:00". If you parsed a date from the "Less common formats"
471           section, the default time was the current time.
472
473           So running a program on Jun 5, 2009 at noon that parsed the
474           following dates gave the following return values:
475
476              Jun 12     =>  Jun 12, 2009 at 00:00:00
477              next week  =>  Jun 12, 2009 at 12:00:00
478
479           This behavior is changed and now relies on the config variable
480           DefaultTime.  If DefaultTime is "curr", the default time for any
481           date which includes no information about the time is the current
482           time. Otherwise, the default time is midnight.
483
484       %z format
485           In Date::Manip 5.xx, the %z format would give an offset in the
486           form: -0500.  Now it gives it in the form: -05:00:00
487

DELTAS

489       Dropped mixed style delta parsing
490           In Date::Manip 5.xx, a parsed delta could be written in the delta
491           style
492
493              1:2:3
494
495           or in a language-specific expanded form:
496
497              1 hour 2 minutes 3 seconds
498
499           or in a mixed form:
500
501              1 hour 2:3
502
503           The mixed form has been dropped since I doubt that it sees much use
504           in real life, and by dropping the mixed form, the parsing is much
505           simpler.
506
507       Approximate date/date calculations
508           In Date::Manip 5.xx, the approximate delta between the two dates:
509
510              Jan 10 1996 noon
511              Jan  7 1998 noon
512
513           was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks).  As of
514           Date::Manip 6.00, the delta is +2:0:-0:3:0:0:0 (or 2 years minus 3
515           days). Although this leads to mixed-sign deltas, it is actually how
516           more people would think about the delta. It has the additional
517           advantage of being MUCH easier and faster to calculate.
518
519       Approximate relationships in deltas
520           When printing parts of deltas in Date::Manip::5.xx, the approximate
521           relationship of 1 year = 365.25 days was used. This is the correct
522           value for the Julian calendar, but for the Gregorian calendar, a
523           better value is 365.2425, and this is used in version 6.00.
524
525       Old style formats
526           The formats used in the printf command are slightly different than
527           in the old Delta_Format command.
528
529           The old formats are described in the Date::Manip::DM5 manual, and
530           the new ones are in the Date::Manip::Delta manual.
531
532           The new formats are much more flexible and I encourage you to
533           switch over, however at this point, the old style formats are
534           officially supported for the Delta_Format command.
535
536           At some point, the old style formats may be deprecated (and removed
537           at some point beyond that), but for now, they are not.
538
539           The old formats are NOT available using the printf method.
540

RECURRENCES

542       The day field meaning changed in a few recurrences
543           The value of the day field can refer to several different things
544           including the day of week number (Monday=1 to Sunday=7), day of
545           month (1-31), day of year (1-366), etc.
546
547           In Date::Manip 5.xx, it could also refer to the nth day of the week
548           (i.e. 1 being the 1st day of the week, -1 being the last day of the
549           week).  This meaning is no longer used in 6.xx.
550
551           For example, the recurrence:
552
553              1*2:3:4:0:0:0
554
555           referred to the 3rd occurrence of the 4th day of the week in
556           February.
557
558           The meaning has been changed to refer to the 3rd occurrence of day
559           4 (Thursday) in February. This is a much more useful type of
560           recurrence.
561
562           As a result of this change, the related recurrence:
563
564              1*2:3:-1:0:0:0
565
566           is invalid. Negative numbers may be used to refer to the nth day of
567           the week, but NOT when referring to the day of week numbers.
568
569       Recurrence range now inclusive
570           Previously, the list of dates implied by the recurrence were on or
571           after the start date, but before the end date.
572
573           This has been changed so that the dates may be on or before the end
574           date.
575
576       Dropped support for a couple English recurrences
577           Date::Manip 5.xx claimed support for a recurrence:
578
579              every 2nd day in June [1997]
580
581           In actuality, this recurrence is not practical to calculate. It
582           requires a base date which might imply June 1,3,5,... in 1997 but
583           June 2,4,6 in 1998.
584
585           In addition, the recurrence does not fit the mold for other
586           recurrences that are an approximate distance apart. This type of
587           recurrence has a number of closely spaced events with 11-month gaps
588           between groups.
589
590           I no longer consider this a valid recurrence and support is now
591           dropped for this string.
592
593           I also dropped the following for a similar reason:
594
595              every 6th Tuesday [in 1999]
596
597       Other minor recurrence changes
598           Previously, ParseRecur would supply default dates if the start or
599           end were missing. This is no longer done.
600

DATE::MANIP FUNCTIONS

602       The Date::Manip module contains the same functions that Date::Manip
603       5.xx had (though the OO modules do all the work now). In general, the
604       routines behave the same as before with the following exceptions:
605
606       Date_ConvTZ
607           Previously, Date_ConvTZ took 1 to 4 arguments and used the local
608           time zone and the ConvTZ config variable to fill in missing
609           arguments.
610
611           Now, the Date_ConvTZ function only supports a 3 argument call:
612
613              $date = Date_ConvTZ($date,$from,$to);
614
615           If $from is not given, it defaults to the local time zone. If $to
616           is not given, it defaults to the local time zone.
617
618           The optional 4th argument ($errlevel) is no longer supported. If
619           there is an error, an empty string is returned.
620
621       DateCalc
622           In Date::Manip 5.xx, it was recommended that you pass arguments to
623           ParseDate or ParseDateDelta. This is not recommended with 6.00
624           since it is much more intelligent about handling the arguments, and
625           you'll just end up parsing the date/delta twice.
626

BUGS AND QUESTIONS

628       Please refer to the Date::Manip::Problems documentation for information
629       on submitting bug reports or questions to the author.
630

SEE ALSO

632       Date::Manip       - main module documentation
633

LICENSE

635       This script is free software; you can redistribute it and/or modify it
636       under the same terms as Perl itself.
637

AUTHOR

639       Sullivan Beck (sbeck@cpan.org)
640
641
642
643perl v5.32.1                      2021-03-03       Date::Manip::Changes5to6(3)
Impressum