1Date::Manip::Problems(3U)ser Contributed Perl DocumentatiDoante::Manip::Problems(3)
2
6 Date::Manip::Problems - problems and bugs
7
9 The following are not bugs in Date::Manip, but they may give some
10 people problems.
11 Unable to determine Time Zone
13 Please refer to the Date::Manip::TZ documentation for a discussion
14 of this problem.
15 Calculations appear to be off by an hour
17 Within days of releasing 6.00, I got the following report:
18 print DateCalc(ParseDate("2009/10/31"), "+1 day"), "\n";
20 print DateCalc(ParseDate("2009/11/01"), "+1 day"), "\n";
21 print DateCalc(ParseDate("2009/11/02"), "+1 day"), "\n";
22 produced:
24 2009110100:00:00
26 2009110123:00:00
27 2009110300:00:00
28 In other words, the second calculation appears to be off by one
30 hour. In actuality, the result is correct. In the user's timezone,
31 daylight saving time ended on Nov 1, and the results are correct.
32 In America/New_York time (which has the same result), the
33 calculation means that:
34 2009-11-01 00:00:00 EDT + 24 hours =
36 2009-11-01 23:00:00 EST
37 which is correct.
39 Missing date formats
41 Due to the large number of date formats that Date::Manip CAN
42 process, people often assume that other formats that they want to
43 use should work as well, and when they don't, it comes as a
44 surprise.
45 With the much improved parsing of 6.00, many formats can be added
47 easily, though unless they are of general use, I'll probably
48 suggest that you use parse_format instead.
49 There is a class of formats that I will not add however.
51 I have frequently been asked to add formats such as "the 15th of
53 last month", or "Monday of next week". I will NOT add these date
54 formats to Date::Manip. Since I have received the request several
55 times, I decided to include my reasoning here.
56 Date::Manip can parse pretty much any static date format that I
58 could think of or find reference to. Dates such as "today", "Jan
59 12", or "2001-01-01" are all understood.
60 These are fairly limited however. Many very common date formats are
62 best thought of as a date plus a modification. For example,
63 "yesterday" is actually determined internally as "today" plus a
64 modification of "- 1 day". "2nd Sunday in June" is determined as
65 "June 1" modified to the 2nd Sunday.
66 As these types of formats were added over time, I quickly realized
68 that the number of possible date plus modification formats was
69 huge. The number of combinations has caused the parsing in
70 Date::Manip to be quite complex, and adding new formats
71 occasionally causes unexpected conflicts with other formats.
72 The first time I received a request similar to "the 15th of last
74 month", I intended to add it, but as I analyzed it to see what
75 changes needed to be made to support it, I realized that this
76 needed to be expressed as a date plus TWO modifications. In other
77 words, today modified to last month modified to the 15th day of the
78 month.
79 As bad as date plus modification formats are, a date plus TWO
81 modifications would be exponentially worse. On realizing that, I
82 made a firm decision that Date::Manip will NOT support this type of
83 format now, or at any time in the future. Although I apologize for
84 the inconvenience, I do not intend to change my position on this.
85 Date::Manip is slow
87 NOTE: The following section applies primarily to 5.xx. I'm doing a
88 lot of work to optimize Date::Manip and I will rewrite this section
89 to take this into account, and to provide performance suggestions.
90 Date::Manip is probably one of the slower Date/Time modules due to
92 the fact that it is huge and written entirely in perl.
93 Some things that will definitely help:
95 ISO-8601 dates are parsed first and fastest. Use them whenever
97 possible.
98 Avoid parsing dates that are referenced against the current time
100 (in 2 days, today at noon, etc.). These take a lot longer to
101 parse.
102 Business date calculations are extremely slow. You should consider
104 alternatives if possible (i.e. doing the calculation in exact mode
105 and then multiplying by 5/7). Who needs a business date more
106 accurate than "6 to 8 weeks" anyway, right :-)
107 RCS Control
109 If you try to put Date::Manip under RCS control, you are going to
110 have problems. Apparently, RCS replaces strings of the form
111 "$Date...$" with the current date. This form occurs all over in
112 Date::Manip. To prevent the RCS keyword expansion, checkout files
113 using:
114 co -ko
116 Since very few people will ever have a desire to do this (and I
118 don't use RCS), I have not worried about it, and I do not intend to
119 try to workaround this problem.
120 Using functions/methods which are not supported
122 There have been a handful of incidents of people using a function
123 from Date::Manip which were not documented in the manual.
124 Date::Manip consists of a large number of user functions which are
126 documented in the manual. These are designed to be used by other
127 programmers, and I will not make any backwards incompatible changes
128 in them unless there is a very compelling reason to do so, and in
129 that case, the change will be clearly documented in the
130 Date::Manip::Changes6 documentation for this module.
131 Date::Manip also consists of a large number of functions which are
133 NOT documented. These are for internal use only. Please do not use
134 them! I can (and do) change their use, and even their name,
135 without notice, and without apology! Some of these internal
136 functions even have test scripts, but that is not a guarantee that
137 they will not change, nor is any support implied. I simply like to
138 run regression tests on as much of Date::Manip as possible.
139 As of the most recent versions of Date::Manip, all internal
141 functions have names that begin with an underscore (_). If you
142 choose to use them directly, it is quite possible that new versions
143 of Date::Manip will cause your programs to break due to a change in
144 how those functions work.
145 Any changes to internal functions will not be documented, and will
147 not be regarded by me as a backwards incompatibility. Nor will I
148 (as was requested in one instance) revert to a previous version of
149 the internal function.
150 If you feel that an internal function is of more general use, feel
152 free to contact me with an argument of why it should be "promoted".
153 I welcome suggestions and will definitely consider any such
154 request.
155
157 If you find a bug in Date::Manip, please send it directly to me (see
158 the AUTHOR section below). Alternately, you can submit it on CPAN.
159 This can be done at the following URL:
160 http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip
162 Please do not use other means to report bugs (such as Usenet
164 newsgroups, or forums for a specific OS or Linux distribution) as it is
165 impossible for me to keep up with all of them.
166 When filing a bug report, please include the following information:
168 · The version of Date::Manip you are using. You can get this by
170 using the script:
171 use Date::Manip;
173 print DateManipVersion(1),"\n";
174 or
176 use Date::Manip::Date;
178 $obj = new Date::Manip::Date;
179 print $obj->version(1),"\n";
180 · The output from "perl -V"
182 If you have a problem using Date::Manip that perhaps isn't a bug (can't
184 figure out the syntax, etc.), you're in the right place. Start by
185 reading the main Date::Manip documentation, and the other documents
186 that apply to whatever you are trying to do. If this still doesn't
187 answer your question, mail me directly.
188 I would ask that you be reasonably familiar with the documentation
190 BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
191 not have time to respond to hundreds of questions which are already
192 answered in this manual.
193 If you find any problems with the documentation (errors, typos, or
195 items that are not clear), please send them to me. I welcome any
196 suggestions that will allow me to improve the documentation.
197
199 None known.
200
202 Date::Manip - main module documentation
203
205 This script is free software; you can redistribute it and/or modify it
206 under the same terms as Perl itself.
207
209 Sullivan Beck (sbeck@cpan.org)
210perl v5.12.0 2010-04-27 Date::Manip::Problems(3)