1Date::Manip::Changes5toU6s(e3r)Contributed Perl DocumentDaattieo:n:Manip::Changes5to6(3)
2
6 Date::Manip::Changes5to6 - describes differences between 5.xx and 6.00
7
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 totally backwards compatible with 5.xx, but some functionality
12 has changed in backwards incompatible ways. Other parts have been
13 deprecated and will be removed at some point in the future.
14 This document describes the differences between the 5.xx series and
16 version 6.00. This page is primarily for someone wanting to know
17 exactly what changed.
18 If you want to make sure that a script which ran with 5.xx will run
20 with 6.xx, refer to the Date::Manip::Migration5to6 document.
21
23 The Date::Manip 5.xx series of suffered from several weaknesses. These
24 included:
25 Minimal time zone support
27 Time zone support in 5.xx was broken. Determining a time zone, and
28 understanding daylight saving time changes was minimal and was
29 missing a lot of necessary functionality.
30 Parsing too complicated and unstructured
32 The parsing routines had grown very complicated, and overly
33 permissive over time and were in need of a complete overhaul.
34 Lacking OO model
36 Date::Manip 5.xx was written as a functional module, not an OO
37 module, but date handling would lend itself very well to being OO
38 with different classes to handle dates, deltas, and recurrences.
39 The OO model allows a lot of information to be stored with each
41 date (such as time zone information) which is discarded in the
42 functional interface.
43 Too monolithic
45 The entire Date::Manip module was contained in one huge file.
46 Breaking up the module would make it much easier to deal with.
47 Date::Manip 6.00 is a complete rewrite of Date::Manip to address these
49 and other issues.
50 The following sections address how Date::Manip 6.00 differs from
52 previous releases, and describes changes that might need to be made to
53 your script in order to upgrade from 5.xx to 6.00.
54 The most important changes are marked with asterisks.
56
58 (*) Requires perl 5.10.0
59 In the past, I've avoided using new features of perl in order to
60 allow Date::Manip to run on older versions of perl. Prior to 5.10,
61 none of the new features would have had a major impact on how
62 Date::Manip was written.
63 However, as I was rewriting all the date parsing, the ability to do
65 named capture buffers allowed me to handle the complicated regular
66 expressions in a dramatically simpler fashion.
67 It was too much to turn down. Hopefully, since 5.10.0 has been out
69 for some time now, this will not prohibit too many people from
70 using the new version of Date::Manip.
71 Please do not request that I rewrite the parsing to be compatible
73 with earlier versions of perl. Although I sympathize with those
74 people who need to use an older version of perl, this is not
75 something that I'm interested in doing.
76 (*) Breaking into smaller modules
78 Date::Manip module has been broken up from one huge module into a
79 large number of smaller more manageable modules. The main
80 Date::Manip module is still present, and contains all of the
81 functions from Date::Manip 5.xx (except that they now call
82 functions from all the other modules to do the actual work). In
83 general, the Date::Manip module from 6.00 is backwards compatible.
84 A number of new modules have been created as well. These can be
86 used directly, bypassing the main Date::Manip module. These include
87 the following:
88 Date::Manip::Base contains many basic date operations which may be
90 used to do simple date manipulation tasks without all the overhead
91 of the full Date::Manip module.
92 Date::Manip::TZ contains time zone operations.
94 Handling dates, deltas, and recurrences are now done in
96 Date::Manip::Date, Date::Manip::Delta, and Date::Manip::Recur.
97 All of these modules are object oriented, and are designed to be
99 used directly, so if you prefer an OO interface over a functional
100 interface, use these modules.
101 (*) Intermediate data cached
103 In order to improve the performance of Date::Manip, many
104 intermediate values are cached. This does impact the memory
105 footprint of the module, but it has a huge impact on the
106 performance of the module.
107 Some types of data depend on the config variables used, and these
109 are cached separately, and this cache is automatically cleared
110 every time a config variable is set. As a result, it is best if you
111 set all config variables at the start, and then leave them alone
112 completely to get optimal use of cached data.
113 A side effect of all this is that the Memoize module should not be
115 used in conjunction with Date::Manip.
116 In the version 5.xx documentation, it was mentioned that the
118 Memoize module might be used to improve performance in some cases.
119 This is no longer the case. It should not be used with Date::Manip,
120 even if you use the functional interface instead of the OO
121 interface.
122 Taint safe
124 Date::Manip now contains no tainted data, and should run without
125 problems with taint checking on provided you do not set additional
126 methods for determining the system timezone using the
127 curr_zone_methods function.
128 Ideally, this should never be necessary. If it is necessary, I'd
130 like to hear about it so that I can add whatever standard methods
131 are needed to the built in list.
132
134 (*) Complete handling of time zones
135 The biggest problem with Date::Manip 5.xx was it's inability to
136 correctly handle time zones and Daylight Saving Time. That is now
137 fixed. Version 6.00 includes support for every time zone included
138 in the zoneinfo (aka Olson) database which includes the definitions
139 of (hopefully) all of the time zones used in the world.
140 Individual time zones will no longer be added
142 Prior to 6.00, time zones were added upon request. Since 6.00 now
143 supports a full set of standard time zones, I will no longer add in
144 individual time zones (Date::Manip::TZ includes functionality for
145 adding them yourself if they are needed). With Date::Manip now
146 having full time zone support, I'm not interested in supporting my
147 own time zone database.
148 However, I am interested in adding sets of time zones from various
150 "standards".
151 For example, Date::Manip 6.00 already includes all zoneinfo time
153 zones, all time zones defined in the Microsoft Windows operating
154 systems, and time zones listed in RFC-822.
155 If there are additional standards that include additional time
157 zones not included here, please point me to them so they can be
158 added. This could include published lists of time zone names
159 supported on some operating system which have different names than
160 the zoneinfo list.
161 Nonstandard time zone abbreviations removed
163 Some of the individual standards that were added in the 5.xx series
164 are not included in any of the standards listed above.
165 As of 6.00, only time zones from standards will be included in the
167 distribution (others can be added by users using the functions
168 described in Date::Manip::TZ to add aliases for existing time
169 zones).
170 The following time zones were in Date::Manip 5.xx but not in 6.00.
172 IDLW -1200 International Date Line West
174 NT -1100 Nome
175 SAT -0400 Chile
176 CLDT -0300 Chile Daylight
177 AT -0200 Azores
178 MEWT +0100 Middle European Winter
179 MEZ +0100 Middle European
180 FWT +0100 French Winter
181 SWT +0100 Swedish Winter
182 MESZ +0200 Middle European Summer
183 FST +0200 French Summer
184 METDST +0200 An alias for MEST used by HP-UX
185 EETDST +0300 An alias for eest used by HP-UX
186 BT +0300 Baghdad, USSR Zone 2
187 IT +0330 Iran
188 ZP4 +0400 USSR Zone 3
189 ZP5 +0500 USSR Zone 4
190 ZP6 +0600 USSR Zone 5
191 AWST +0800 Australian Western Standard
192 ROK +0900 Republic of Korea
193 CHST +1000 Guam Standard, USSR Zone 9
194 AEST +1000 Australian Eastern Standard
195 ACDT +1030 Australian Central Daylight
196 CADT +1030 Central Australian Daylight
197 AEDT +1100 Australian Eastern Daylight
198 EADT +1100 Eastern Australian Daylight
199 NZT +1200 New Zealand
200 IDLE +1200 International Date Line East
201 A lot of support modules and files
203 Date::Manip now includes a large number of files and modules that
204 are used to support time zones.
205 A series of modules are included which are auto-generated from the
207 zoneinfo database. The Date::Manip::Zones, Date::Manip::TZ::*, and
208 Date::Manip::Offset::* modules are all automatically generated and
209 are not intended to be used directly. Instead, the Date::Manip::TZ
210 module is used to access the data stored there.
211 A separate time zone module (Date::Manip::TZ::*) is included for
213 every single time zone. There is also a module
214 (Date::Manip::Offset::*) for every different offset. All told,
215 there are almost 1000 modules. These are included to make time
216 zone handling more efficient. Rather than calculating everything on
217 the fly, information about each time zone and offset are included
218 here which greatly speeds up the handling of time zones. These
219 modules are only loaded as needed (i.e. only the modules related to
220 the specific time zones you refer to are ever loaded), so there is
221 no performance penalty to having them.
222 Also included in the distribution are a script (tzdata) and
224 additional module (Date::Manip::TZdata). These are used to
225 automatically generate the time zone modules, and are of no use to
226 anyone other than the maintainer of Date::Manip. They are included
227 solely for the sake of completeness. If someone wanted to fork
228 Date::Manip, all the tools necessary to do so are included in the
229 distribution.
230 (*) Meaning of $::TZ and $ENV{TZ}
232 In Date::Manip 5.x, you could specify what time zone you wanted to
233 work in using either the $::TZ or $ENV{TZ} variables.
234 Date::Manip 6.00 makes use of two different time zones: the actual
236 local time zone the computer is running in (and which is used by
237 the system clock), and a time zone that you want to work in.
238 Typically, these are the same, but they do not have to be.
239 As of Date::Manip 6.00, the $::TZ and $ENV{TZ} variables are used
241 only to specify the actual local time zone.
242 In order to specify an alternate time zone to work in, use the
244 SetDate or ForceDate config variables.
245
247 (*) Date_Init handling of config variables
248 The handling of config variables has changed slightly.
249 Previously, variables passed in to Date_Init overrode values from
251 config files. This has changed slightly. Options to Date_Init are
252 now parsed in the order they are listed, so the following:
253 Date_Init("DateFormat=Other","ConfigFile=DateManip.cnf")
255 would first set the DateFormat variable, and then it would read the
257 config file "DateManip.cnf". If that config file included a
258 DateFormat definition, it would override the one passed in to
259 Date_Init.
260 The proper way to override config files is to pass the config files
262 in first, followed by any script-specific overrides. In other
263 words:
264 Date_Init("ConfigFile=DateManip.cnf","DateFormat=Other")
266 Date_Init doesn't return the config variables
268 In Date::Manip::5.xx, Date_Init could return the list of all config
269 variables. This functionality is no longer supported. Date_Init is
270 used strictly to set config variables.
271 (*) Config file options
273 Date::Manip 5.xx had the concept of a global and personal config
274 file. In addition, the personal config file could be looked for in
275 a path of directories. All this was specified using the config
276 variables:
277 GlobalCnf
279 IgnoreGlobalCnf
280 PersonalCnf
281 PersonalCnfPath
282 PathSep
283 All of these are now deprecated. They will continue to work for a
285 while, but they will be removed at some point. Instead, the single
286 config variable:
287 ConfigFile
289 will be used to specify config files (with no distinction between a
291 global and personal config file). Also, no path searching is done.
292 Each must be specified by a complete path. Finally, any number of
293 config files can be used. So the following is valid:
294 Date_Init("ConfigFile=./Manip.cnf","ConfigFile=/tmp/Manip.cnf")
296 TodayIsMidnight removed
298 The TodayIsMidnight variable is no longer supported. The
299 DefaultTime variable can be used instead.
300 Other config variables deprecated
302 The following config variables are deprecated and will be removed
303 in some future version:
304 TZ Use SetDate or ForceDate instead.
306 ConvTZ Ignored. Time zone handling is done
308 automatically, so this is no longer
309 necessary.
310 Internal Renamed to Printable (Internal still
312 works for a while)
313 DeltaSigns Ignored. Use the Date::Manip::Delta::printf
315 method to print deltas
316 UpdateCurrTZ Ignored. With real time zone handling in
318 place, this is no longer necessary
319 Holidays
321 Previously, holidays could be defined as a "Date + Delta" or "Date
322 - Delta" string. These predate recurrences, and introduce some
323 complexity into the handling of holidays. Since recurrences are a
324 much better way to define holidays, the "Date + Delta" and "Date -
325 Delta" strings are no longer supported.
326 TZ replaced (and enhanced)
328 The SetDate and ForceDate variables (which include the
329 functionality of the deprecated TZ variable) are much improved as
330 described in the Date::Manip::Config documentation.
331 Since it is now handles time change correctly (allowing time
333 changes to occur in the alternate time zone), parsed results may be
334 different than in 5.x (but since 5.x didn't have proper time zone
335 handling, this is a good thing).
336
338 (*) today, tomorrow, yesterday
339 The words "today", "tomorrow", and "yesterday" in 5.xx referred to
340 the now, 24 hours in the future, and 24 hours in the past
341 respectively.
342 As of 6.00, these are treated strictly as date strings, so they are
344 the current day, the day before, or the day after at the time
345 00:00:00.
346 The string "now" still refers to the current date and time.
348 ISO 8601 formats
350 A couple of the date formats from Date::Manip 5.xx conflicted with
351 ISO 8601 formats in the spec. These are documented in the
352 Date::Manip::Date documentation.
353 Dates are now parsed according to the spec (though a couple
355 extensions have been made, which are also documented in the
356 Date::Manip::Date documentation).
357 There is one change with respect to Date::Manip 5.xx that results
359 from a possible misinterpretation of the standard.
360 There is a small amount of ambiguity in how the Www-D date formats
362 are understood.
363 The date:
365 1996-w02-3
367 might be interpreted in two different ways. It could be interpreted
369 as Wednesday (day 3) of the 2nd week of 1996, or as the 3rd day of
370 the 2nd week of 1996 (which would be Tuesday if the week begins on
371 Sunday). Since the specification only works with weeks which begin
372 on day 1, the two are always equivalent in the specification, and
373 the language of the specification doesn't clearly indicate one
374 interpretation over the other.
375 Since Date::Manip supports the concept of weeks starting on days
377 other than day 1 (Monday), the two interpretations are not
378 equivalent.
379 In Date::Manip 5.xx, the date was interpreted as Wednesday of the
381 2nd week, but I now believe that the other interpretation (3rd day
382 of the week) is the interpretation intended by the specification.
383 In addition, if this interpretation is used, it is easy to get the
384 other interpretation.
385 If 1996-w02-3 means the 3rd day of the 2nd week, then to get
387 Wednesday (day 3) of the week, use the following two
388 Date::Manip::Date methods:
389 $err = $date->parse("1996-w02-1");
391 $date2 = $date->next(3,1);
392 The first call gets the 1st day of the 2nd week, and the second
394 call gets the next Wednesday.
395 If 1996-w02-3 is interpreted as Wednesday of the 2nd week, then to
397 get the 3rd day of the week involves significantly more work.
398 In Date::Manip 6.00, the date will now be parsed as the 3rd day of
400 the 2nd week.
401 (*) Parsing is now more rigid
403 The philosophy in Date::Manip 5.xx with respect to parsing dates
404 was "if there's any conceivable way to find a valid date in the
405 string, do so". As a result, strings which did not look like they
406 could contain a valid date often would.
407 This manifested itself it two ways. First, a lot of punctuation was
409 ignored. For example, the string "01 // 03 -. 75" was the date
410 1975-01-03.
411 Second, a lot of word breaks were optional and it was often
413 acceptable to run strings together. For example, the delta
414 "in5seconds" would have worked.
415 With Date::Manip 6.00, parsing now tries to find a valid date in
417 the string, but uses a more rigidly defined set of allowed formats
418 which should more closely match how the dates would actually be
419 expressed in real life. The punctuation allowed is more rigidly
420 defined, and word breaks are required. So "01/03/75" will work, but
421 "01//03/75" and "01/03-75" won't. Also, "in5seconds" will no longer
422 work, though "in 5 seconds" will work.
423 These changes serve to simplify some of the regular expressions
425 used in parsing dates, as well as simplifying the parsing routines.
426 They also help to recognize actually dates as opposed to typos...
427 it was too easy to pass in garbage and get a date out.
428 Support dropped for a few formats
430 I've dropped support for a few very uncommon (probably never used)
431 formats. These include (with Jan 3, 2009 as an example):
432 DD/YYmmm 03/09Jan
434 DD/YYYYmmm 03/2009Jan
435 mmmYYYY/DD Jan2009/03
436 YYYY/DDmmm 2009/03Jan
437 mmmYYYY Jan2009
439 YYYYmmm 2009Jan
440 The last two are no longer supported since they are incomplete.
442 With the exception of the incomplete forms, these could be added
444 back in with very little effort. If there is ever a request to do
445 so, I probably will.
446 No longer parses the Apache format
448 Date::Manip 5.xx supported the format:
449 DD/mmm/YYYY:HH:MN:SS
451 used in the apache logs. Due to the stricter parsing, this format
453 is no longer supported directly. However, the parse_format method
454 may be used to parse the date directly from an apache log line with
455 no need to extract the date string beforehand.
456 Date_PrevWorkDay behavior
458 The behavior of Date_PrevWorkDay has changed slightly.
459 The starting date is checked. If $timecheck was non-zero, the check
461 failed if the date was not a business date, or if the time was not
462 during business hours. If $timecheck was zero, the check failed if
463 the date was not a business date, but the time was ignored.
464 In 5.xx, if the check failed, and $timecheck was non-zero, day 0
466 was defined as the start of the next business day, but if
467 $timecheck was zero, day 0 was defined as the previous business day
468 at the same time.
469 In 6.x, if the check fails, and $timecheck is non-zero, the
471 behavior is the same as before. If $timecheck is zero, day 0 is
472 defined as the next business day at the same time.
473 So day 0 is now always the same, where before, day 0 meant two
475 different things depending on whether $timecheck was zero or not.
476 (*) Default time
478 In Date::Manip 5.xx, the default times for dates was handled in an
479 inconsistent manner. In the Date::Manip::Date documentation, if
480 you parse a date from the "Common date formats" section, in
481 Date::Manip 5.xx, if no time was included, it defaulted to
482 "00:00:00". If you parsed a date from the "Less common formats"
483 section, the default time was the current time.
484 So running a program on Jun 5, 2009 at noon that parsed the
486 following dates gave the following return values:
487 Jun 12 => Jun 12, 2009 at 00:00:00
489 next week => Jun 12, 2009 at 12:00:00
490 This behavior is changed and now relies on the config variable
492 DefaultTime. If DefaultTime is "curr", the default time for any
493 date which includes no information about the time is the current
494 time. Otherwise, the default time is midnight.
495 %z format
497 In Date::Manip 5.xx, the %z format would give an offset in the
498 form: -0500. Now it gives it in the form: -05:00:00
499
501 Dropped mixed style delta parsing
502 In Date::Manip 5.xx, a parsed delta could be written in the delta
503 style
504 1:2:3
506 or in a language-specific expanded form:
508 1 hour 2 minutes 3 seconds
510 or in a mixed form:
512 1 hour 2:3
514 The mixed form has been dropped since I doubt that it sees much use
516 in real life, and by dropping the mixed form, the parsing is much
517 simpler.
518 Approximate date/date calculations
520 In Date::Manip 5.xx, the approximate delta between the two dates:
521 Jan 10 1996 noon
523 Jan 7 1998 noon
524 was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). As of
526 Date::Manip 6.0, the delta is +2:0:-0:3:0:0:0 (or 2 years minus 3
527 days). Although this leads to mixed-sign deltas, it is actually how
528 more people would think about the delta. It has the additional
529 advantage of being MUCH easier and faster to calculate.
530 Approximate relationships in deltas
532 When printing parts of deltas in Date::Manip::5.xx, the approximate
533 relationship of 1 year = 365.25 days was used. This is the correct
534 value for the Julian calendar, but for the Gregorian calendar, a
535 better value is 365.2425, and this is used in version 6.00.
536 Old style formats
538 The formats used in the printf command are slightly different than
539 in the old Delta_Format command.
540 The old formats are described in the Date::Manip manual, and the
542 new ones are in the Date::Manip::Delta manual.
543 The new formats are much more flexible and I encourage you to
545 switch over, however at this point, the old style formats are
546 officially supported for the Delta_Format command.
547 At some point, the old style formats may be deprecated (and removed
549 at some point beyond that), but for now, they are not.
550 The old formats are NOT available using the printf method.
552
554 The day field meaning changed in a few recurrences
555 The value of the day field can refer to several different things
556 including the day of week number (Monday=1 to Sunday=7), nth day of
557 week (1 being the 1st day of the week, -1 being the last day of the
558 week), and others.
559 In Date::Manip 5.xx, the 2nd of these two definitions was used in a
561 few cases.
562 For example, the recurrence:
564 1*2:3:4:0:0:0
566 referred to the 3rd occurence of the 4th day of the week in
568 February.
569 The meaning has been changed to refer to the 3rd occurence of day 4
571 (Thursday) in February. This is a much more useful type of
572 recurrence.
573 As a result of this change, the related recurrence:
575 1*2:3:-1:0:0:0
577 is invalid. Negative numbers may be used to refer to the nth day of
579 the week, but NOT when referring to the day of week numbers.
580 Recurrence range now inclusive
582 Previously, the list of dates implied by the recurrence were on or
583 after the start date, but before the end date.
584 This has been changed so that the dates may be on or before the end
586 date.
587 Dropped support for a couple English recurrences
589 Date::Manip 5.xx claimed support for a recurrence:
590 every 2nd day in June [1997]
592 In actuality, this recurrence is not practical to calculate. It
594 requires a base date which might imply June 1,3,5,... in 1997 but
595 June 2,4,6 in 1998.
596 In addition, the recurrence does not fit the mold for other
598 recurrences that are an approximate distance apart. This type of
599 recurrence has a number of closely spaced events with 11-month gaps
600 between groups.
601 I no longer consider this a valid recurrence and support is now
603 dropped for this string.
604 I also dropped the following for a similar reason:
606 every 6th tuesday [in 1999]
608 Other minor recurrence changes
610 Previously, ParseRecur would supply default dates if the start or
611 end were missing. This is no longer done.
612
614 The Date::Manip module contains the same functions that Date::Manip
615 5.xx had (though the OO modules do all the work now). In general, the
616 routines behave the same as before with the following exceptions:
617 Date_ConvTZ
619 Previously, Date_ConvTZ took 1 to 4 arguments and used the local
620 time zone and the ConvTZ config variable to fill in missing
621 arguments.
622 Now, the Date_ConvTZ function only supports a 3 argument call:
624 $date = Date_ConvTZ($date,$from,$to);
626 If $from is not given, it defaults to the local time zone. If $to
628 is not given, it defaults to the local time zone.
629 The optional 4th argument ($errlevel) is no longer supported. If
631 there is an error, an empty string is returned.
632 DateCalc
634 In Date::Manip 5.xx, it was recommended that you pass arguments to
635 ParseDate or ParseDateDelta. This is not recommended with 6.00
636 since it is much more intelligent about handling the arguments, and
637 you'll just end up parsing the date/delta twice.
638
640 Please refer to the Date::Manip::Problems documentation for information
641 on submitting bug reports or questions to the author.
642
644 Date::Manip - main module documentation
645
647 This script is free software; you can redistribute it and/or modify it
648 under the same terms as Perl itself.
649
651 Sullivan Beck (sbeck@cpan.org)
652perl v5.12.0 2010-04-27 Date::Manip::Changes5to6(3)