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 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 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
22 The Date::Manip 5.xx series of suffered from several weaknesses. These
23 included:
24 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 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 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 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 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 Date::Manip 6.00 is a complete rewrite of Date::Manip to address these
48 and other issues.
49 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 The most important changes are marked with asterisks.
55
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 (*) 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 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 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 Date::Manip::TZ contains time zone operations.
78 Handling dates, deltas, and recurrences are now done in
80 Date::Manip::Date, Date::Manip::Delta, and Date::Manip::Recur.
81 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 (*) 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 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 A side effect of all this is that the Memoize module should not be
99 used in conjunction with Date::Manip.
100 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 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 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
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 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 However, I am interested in adding sets of time zones from various
134 "standards".
135 Date::Manip 6.00 includes time zones from the following standards:
137 Olson zoneinfo database
139 all Microsoft Windows time zones
140 zones listed in RFC-822
141 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 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 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 The following time zones were in Date::Manip 5.xx but not in 6.00.
158 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 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 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 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 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 (*) 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 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 As of Date::Manip 6.00, the $::TZ and $ENV{TZ} variables are used
229 only to specify the actual local time zone.
230 In order to specify an alternate time zone to work in, use the
232 SetDate or ForceDate config variables.
233
235 (*) Date_Init handling of config variables
236 The handling of config variables has changed slightly.
237 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 Date_Init("DateFormat=Other","ConfigFile=DateManip.cnf")
243 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 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 Date_Init("ConfigFile=DateManip.cnf","DateFormat=Other")
254 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 (*) 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 GlobalCnf
267 IgnoreGlobalCnf
268 PersonalCnf
269 PersonalCnfPath
270 PathSep
271 All of these are now deprecated. They will continue to work for a
273 while, but they will be removed at some point. Instead, the single
274 config variable:
275 ConfigFile
277 will be used to specify config files (with no distinction between a
279 global and personal config file). Also, no path searching is done.
280 Each must be specified by a complete path. Finally, any number of
281 config files can be used. So the following is valid:
282 Date_Init("ConfigFile=./Manip.cnf","ConfigFile=/tmp/Manip.cnf")
284 TodayIsMidnight removed
286 The TodayIsMidnight variable is no longer supported. The
287 DefaultTime variable can be used instead.
288 Other config variables deprecated
290 The following config variables are deprecated and will be removed
291 in some future version:
292 TZ Use SetDate or ForceDate instead.
294 ConvTZ Ignored. Time zone handling is done
296 automatically, so this is no longer
297 necessary.
298 Internal Renamed to Printable (Internal still
300 works for a while)
301 DeltaSigns Ignored. Use the Date::Manip::Delta::printf
303 method to print deltas
304 UpdateCurrTZ Ignored. With real time zone handling in
306 place, this is no longer necessary
307 IntCharSet This has been replaced with better support for
309 international character sets. The Encoding config
310 variable may be used.
311 Holidays
313 Previously, holidays could be defined as a "Date + Delta" or "Date
314 - Delta" string. These predate recurrences, and introduce some
315 complexity into the handling of holidays. Since recurrences are a
316 much better way to define holidays, the "Date + Delta" and "Date -
317 Delta" strings are no longer supported.
318 TZ replaced (and enhanced)
320 The SetDate and ForceDate variables (which include the
321 functionality of the deprecated TZ variable) are much improved as
322 described in the Date::Manip::Config documentation.
323 Since it is now handles time change correctly (allowing time
325 changes to occur in the alternate time zone), parsed results may be
326 different than in 5.x (but since 5.x didn't have proper time zone
327 handling, this is a good thing).
328
330 (*) today, tomorrow, yesterday
331 The words "today", "tomorrow", and "yesterday" in 5.xx referred to
332 the time now, 24 hours in the future, and 24 hours in the past
333 respectively.
334 As of 6.00, these are treated strictly as date strings, so they are
336 the current day, the day before, or the day after at the time
337 00:00:00.
338 The string "now" still refers to the current date and time.
340 ISO 8601 formats
342 A couple of the date formats from Date::Manip 5.xx conflicted with
343 ISO 8601 formats in the spec. These are documented in the
344 Date::Manip::Date documentation.
345 Dates are now parsed according to the spec (though a couple
347 extensions have been made, which are also documented in the
348 Date::Manip::Date documentation).
349 There is one change with respect to Date::Manip 5.xx that results
351 from a possible misinterpretation of the standard. In Date::Manip,
352 there is a small amount of ambiguity in how the Www-D date formats
353 are understood.
354 The date:
356 1996-w02-3
358 might be interpreted in two different ways. It could be interpreted
360 as Wednesday (day 3) of the 2nd week of 1996, or as the 3rd day of
361 the 2nd week of 1996 (which would be Tuesday if the week begins on
362 Sunday). Since the specification only works with weeks which begin
363 on day 1, the two are always equivalent in the specification, and
364 the language of the specification doesn't clearly indicate one
365 interpretation over the other.
366 Since Date::Manip supports the concept of weeks starting on days
368 other than day 1 (Monday), the two interpretations are not
369 equivalent.
370 In Date::Manip 5.xx, the date was interpreted as Wednesday of the
372 2nd week, but I now believe that the other interpretation (3rd day
373 of the week) is the interpretation intended by the specification.
374 In addition, if this interpretation is used, it is easy to get the
375 other interpretation.
376 If 1996-w02-3 means the 3rd day of the 2nd week, then to get
378 Wednesday (day 3) of the week, use the following two
379 Date::Manip::Date methods:
380 $err = $date->parse("1996-w02-1");
382 $date2 = $date->next(3,1);
383 The first call gets the 1st day of the 2nd week, and the second
385 call gets the next Wednesday.
386 If 1996-w02-3 is interpreted as Wednesday of the 2nd week, then to
388 get the 3rd day of the week involves significantly more work.
389 In Date::Manip 6.00, the date will now be parsed as the 3rd day of
391 the 2nd week.
392 (*) Parsing is now more rigid
394 The philosophy in Date::Manip 5.xx with respect to parsing dates
395 was "if there's any conceivable way to find a valid date in the
396 string, do so". As a result, strings which did not look like they
397 could contain a valid date often would.
398 This manifested itself it two ways. First, a lot of punctuation was
400 ignored. For example, the string "01 // 03 -. 75" was the date
401 1975-01-03.
402 Second, a lot of word breaks were optional and it was often
404 acceptable to run strings together. For example, the delta
405 "in5seconds" would have worked.
406 With Date::Manip 6.00, parsing now tries to find a valid date in
408 the string, but uses a more rigidly defined set of allowed formats
409 which should more closely match how the dates would actually be
410 expressed in real life. The punctuation allowed is more rigidly
411 defined, and word breaks are required. So "01/03/75" will work, but
412 "01//03/75" and "01/03-75" won't. Also, "in5seconds" will no longer
413 work, though "in 5 seconds" will work.
414 These changes serve to simplify some of the regular expressions
416 used in parsing dates, as well as simplifying the parsing routines.
417 They also help to recognize actually dates as opposed to typos...
418 it was too easy to pass in garbage and get a date out.
419 Support dropped for a few formats
421 I've dropped support for a few very uncommon (probably never used)
422 formats. These include (with Jan 3, 2009 as an example):
423 DD/YYmmm 03/09Jan
425 DD/YYYYmmm 03/2009Jan
426 mmmYYYY/DD Jan2009/03
427 YYYY/DDmmm 2009/03Jan
428 mmmYYYY Jan2009
430 YYYYmmm 2009Jan
431 The last two are no longer supported since they are incomplete.
433 With the exception of the incomplete forms, these could be added
435 back in with very little effort. If there is ever a request to do
436 so, I probably will.
437 No longer parses the Apache format
439 Date::Manip 5.xx supported the format:
440 DD/mmm/YYYY:HH:MN:SS
442 used in the apache logs. Due to the stricter parsing, this format
444 is no longer supported directly. However, the parse_format method
445 may be used to parse the date directly from an apache log line with
446 no need to extract the date string beforehand.
447 Date_PrevWorkDay behavior
449 The behavior of Date_PrevWorkDay has changed slightly.
450 The starting date is checked. If $timecheck was non-zero, the check
452 failed if the date was not a business date, or if the time was not
453 during business hours. If $timecheck was zero, the check failed if
454 the date was not a business date, but the time was ignored.
455 In 5.xx, if the check failed, and $timecheck was non-zero, day 0
457 was defined as the start of the next business day, but if
458 $timecheck was zero, day 0 was defined as the previous business day
459 at the same time.
460 In 6.x, if the check fails, and $timecheck is non-zero, the
462 behavior is the same as before. If $timecheck is zero, day 0 is
463 defined as the next business day at the same time.
464 So day 0 is now always the same, where before, day 0 meant two
466 different things depending on whether $timecheck was zero or not.
467 (*) Default time
469 In Date::Manip 5.xx, the default times for dates was handled in an
470 inconsistent manner. In the Date::Manip::Date documentation, if
471 you parse a date from the "Common date formats" section, in
472 Date::Manip 5.xx, if no time was included, it defaulted to
473 "00:00:00". If you parsed a date from the "Less common formats"
474 section, the default time was the current time.
475 So running a program on Jun 5, 2009 at noon that parsed the
477 following dates gave the following return values:
478 Jun 12 => Jun 12, 2009 at 00:00:00
480 next week => Jun 12, 2009 at 12:00:00
481 This behavior is changed and now relies on the config variable
483 DefaultTime. If DefaultTime is "curr", the default time for any
484 date which includes no information about the time is the current
485 time. Otherwise, the default time is midnight.
486 %z format
488 In Date::Manip 5.xx, the %z format would give an offset in the
489 form: -0500. Now it gives it in the form: -05:00:00
490
492 Dropped mixed style delta parsing
493 In Date::Manip 5.xx, a parsed delta could be written in the delta
494 style
495 1:2:3
497 or in a language-specific expanded form:
499 1 hour 2 minutes 3 seconds
501 or in a mixed form:
503 1 hour 2:3
505 The mixed form has been dropped since I doubt that it sees much use
507 in real life, and by dropping the mixed form, the parsing is much
508 simpler.
509 Approximate date/date calculations
511 In Date::Manip 5.xx, the approximate delta between the two dates:
512 Jan 10 1996 noon
514 Jan 7 1998 noon
515 was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). As of
517 Date::Manip 6.0, the delta is +2:0:-0:3:0:0:0 (or 2 years minus 3
518 days). Although this leads to mixed-sign deltas, it is actually how
519 more people would think about the delta. It has the additional
520 advantage of being MUCH easier and faster to calculate.
521 Approximate relationships in deltas
523 When printing parts of deltas in Date::Manip::5.xx, the approximate
524 relationship of 1 year = 365.25 days was used. This is the correct
525 value for the Julian calendar, but for the Gregorian calendar, a
526 better value is 365.2425, and this is used in version 6.00.
527 Old style formats
529 The formats used in the printf command are slightly different than
530 in the old Delta_Format command.
531 The old formats are described in the Date::Manip manual, and the
533 new ones are in the Date::Manip::Delta manual.
534 The new formats are much more flexible and I encourage you to
536 switch over, however at this point, the old style formats are
537 officially supported for the Delta_Format command.
538 At some point, the old style formats may be deprecated (and removed
540 at some point beyond that), but for now, they are not.
541 The old formats are NOT available using the printf method.
543
545 The day field meaning changed in a few recurrences
546 The value of the day field can refer to several different things
547 including the day of week number (Monday=1 to Sunday=7), day of
548 month (1-31), day of year (1-366), etc.
549 In Date::Manip 5.xx, it could also refer to the nth day of the week
551 (i.e. 1 being the 1st day of the week, -1 being the last day of the
552 week). This meaning is no longer used in 6.xx.
553 For example, the recurrence:
555 1*2:3:4:0:0:0
557 referred to the 3rd occurence of the 4th day of the week in
559 February.
560 The meaning has been changed to refer to the 3rd occurence of day 4
562 (Thursday) in February. This is a much more useful type of
563 recurrence.
564 As a result of this change, the related recurrence:
566 1*2:3:-1:0:0:0
568 is invalid. Negative numbers may be used to refer to the nth day of
570 the week, but NOT when referring to the day of week numbers.
571 Recurrence range now inclusive
573 Previously, the list of dates implied by the recurrence were on or
574 after the start date, but before the end date.
575 This has been changed so that the dates may be on or before the end
577 date.
578 Dropped support for a couple English recurrences
580 Date::Manip 5.xx claimed support for a recurrence:
581 every 2nd day in June [1997]
583 In actuality, this recurrence is not practical to calculate. It
585 requires a base date which might imply June 1,3,5,... in 1997 but
586 June 2,4,6 in 1998.
587 In addition, the recurrence does not fit the mold for other
589 recurrences that are an approximate distance apart. This type of
590 recurrence has a number of closely spaced events with 11-month gaps
591 between groups.
592 I no longer consider this a valid recurrence and support is now
594 dropped for this string.
595 I also dropped the following for a similar reason:
597 every 6th tuesday [in 1999]
599 Other minor recurrence changes
601 Previously, ParseRecur would supply default dates if the start or
602 end were missing. This is no longer done.
603
605 The Date::Manip module contains the same functions that Date::Manip
606 5.xx had (though the OO modules do all the work now). In general, the
607 routines behave the same as before with the following exceptions:
608 Date_ConvTZ
610 Previously, Date_ConvTZ took 1 to 4 arguments and used the local
611 time zone and the ConvTZ config variable to fill in missing
612 arguments.
613 Now, the Date_ConvTZ function only supports a 3 argument call:
615 $date = Date_ConvTZ($date,$from,$to);
617 If $from is not given, it defaults to the local time zone. If $to
619 is not given, it defaults to the local time zone.
620 The optional 4th argument ($errlevel) is no longer supported. If
622 there is an error, an empty string is returned.
623 DateCalc
625 In Date::Manip 5.xx, it was recommended that you pass arguments to
626 ParseDate or ParseDateDelta. This is not recommended with 6.00
627 since it is much more intelligent about handling the arguments, and
628 you'll just end up parsing the date/delta twice.
629
631 Please refer to the Date::Manip::Problems documentation for information
632 on submitting bug reports or questions to the author.
633
635 Date::Manip - main module documentation
636
638 This script is free software; you can redistribute it and/or modify it
639 under the same terms as Perl itself.
640
642 Sullivan Beck (sbeck@cpan.org)
643perl v5.10.1 2011-12-07 Date::Manip::Changes5to6(3)