1Date::Manip(3) User Contributed Perl Documentation Date::Manip(3)
2
6 Date::Manip - Date manipulation routines
7
9 Date::Manip is a series of modules designed to make any common
10 date/time operation easy to do. Operations such as comparing two
11 times, calculating a time a given amount of time from another, or
12 parsing international times are all easily done. It deals with time as
13 it is used in the Gregorian calendar (the one currently in use) with
14 full support for time changes due to daylight saving time.
15 From the very beginning, the main focus of Date::Manip has been to be
17 able to do ANY desired date/time operation easily. Many other modules
18 exist which may do a subset of these operations quicker or more
19 efficiently, but no other module can do all of the operations available
20 in Date::Manip.
21 Since many other date/time modules exist, some of which may do the
23 specific operation(s) you need faster, be sure to read the section
24 SHOULD I USE DATE::MANIP in the Date::Manip::Misc document before
25 deciding which of the Date and Time modules from CPAN is for you.
26 However, if you want one module to do it all, Date::Manip is the one to
27 use.
28 Date::Manip has functionality to work with several fundamental types of
30 data.
31 dates
33 The word date is used extensively here and is somewhat misleading.
34 In Date::Manip, a date consists of three pieces of information: a
35 calendar date, a time of day, and time zone information. Calendar
36 dates and times are fully handled. Time zones are handled as well,
37 but depending on how you use Date::Manip, there may be some
38 limitations as discussed below.
39 delta
41 A delta is an amount of time (i.e. the amount of time between two
42 different dates). A delta refers only to an amount of time. It
43 includes no information about a starting or ending date/time.
44 recurrence
46 A recurring event is something which occurs on a regular recurring
47 basis.
48 holidays and events
50 Holidays and events are basically named dates or recurrences.
51 Among other things, Date::Manip allow you to:
53 * Enter a date in practically any format you choose.
55 * Compare two dates, entered in widely different formats to determine
57 which is earlier.
58 * Extract any information you want from a date using a format string
60 similar to the Unix date command.
61 * Determine the amount of time between two dates, or add an amount of
63 time to a date to get a second date.
64 * Work with dates with dates using international formats (foreign
66 month names, 12/10/95 referring to October rather than December,
67 etc.).
68 * To find a list of dates where a recurring event happens.
70 Each of these tasks is trivial (one or two lines at most) with this
72 package.
73
75 Date::Manip version 6.00 was a complete rewrite of the module (for more
76 information, please refer to the Date::Manip::Changes5to6 document).
77 The rewrite made use of features introduced in perl 5.10 which made the
78 date parsing routines significantly more robust. However, since not
79 everyone has access to a new version of perl where Date::Manip is
80 needed, the Date::Manip distribution actually includes two different
81 versions of the module. It includes the older (5.xx) release and the
82 newer (6.xx) release.
83 In addition, the 6.xx release was written with both a functional and an
85 object-oriented interface, so there are actually three different ways
86 to use Date::Manip (though only one is available if you have a version
87 of perl older than 5.10).
88 For those who still run an older version of perl, the 5.xx functional
90 interface is still available. It is known to work with perl 5.6 (and
91 probably works with even older versions of perl). There are some
92 limitations to this as described below.
93 Version 6.xx was rewritten as a series of object-oriented modules, but
95 a functional interface (which is mostly backward compatible with the
96 version 5 functional interface) is included. The functional interface
97 is simply wrapper functions which call the OO modules.
98 A more detailed description of each interface is included below (to
100 help you decide which interface is right for you). If you already know
101 which interface you want to use, just go to the SEE ALSO section below
102 for instructions on using each interface.
103 It should be noted that all three interfaces will be installed, but
105 they will only all be usable with a recent version of perl.
106
108 When using a version of perl older than 5.10, this is the only
109 interface available. This interface is documented in the
110 Date::Manip::DM5 document. This interface has several weaknesses that
111 need to be understood when using it:
112 Limited Support
114 The version 5 functional interface is no longer being developed,
115 and only limited support is available for it.
116 I will continue to do limited bug fixes provided they do not
118 require a lot of changes. Anything to do with time zone handling
119 will not be fixed, and other problems (especially those that have
120 already been fixed in the 6.xx release) may not be patched if they
121 require significant changes to 5.xx.
122 Limited bug fixes will be supported until December 2012. At that
124 point, I will reevaluate things and decide whether or not to
125 continue this or not. My prediction is that, at that point, I will
126 cease providing bug fixes for the 5.xx release entirely.
127 Whether or not I continue to do bug fixes, I will continue to
129 distribute the version 5 functional interface until at least
130 December 2013. After that, I will evaluate the need for a perl
131 5.6/5.8 version of Date::Manip in order to decide whether or not to
132 continue distributing it.
133 Limited Time Zone Support
135 Time zone support is extremely limited, and is often broken. The
136 lack of good time zone support was the primary reason for rewriting
137 Date::Manip .
138 Time zone information for 5.xx is now automatically generated from
140 the 6.xx time zone list, and every time time zones are updated in
141 6.xx, the 5.xx release will be similarly updated.
142 Prior to the release of 6.00, time zones were added manually to
144 Date::Manip upon request. Since time zone information in 5.xx is
145 now automatically generated, I no longer take requests for time
146 zones.
147 The version 5 interface does not handle daylight saving time
149 changes properly.
150 No Further Development
152 No functionality will be added to 5.xx .
153 Performance Issues
155 Considerable time has been spent speeding up Date::Manip, and
156 fairly simple benchmarks show that version 6 is around twice as
157 fast as version 5.
158 Feel free to email me concerns and comments.
160
162 The version 6 functional interface is almost completely identical to
163 the version 5 functional interface, except that it uses the object-
164 oriented modules to do all the real work.
165 Time zone support is greatly improved, but is still somewhat limited.
167 Since the version 6 interface is backward compatible, dates do not
168 store time zone information in them, so the programmer is responsible
169 for keeping track of what time zone each date is in. If you want full
170 access to the time zone support offered in Date::Manip, you have to use
171 the object-oriented interface.
172 For the most part, scripts written for older versions of Date::Manip
174 will continue to work (and scripts written for the version 6 functional
175 interface will run with the version 5 interface), however in a few
176 cases, you may need to modify your scripts. Please refer to the
177 Date::Manip::Migration5to6 document for a list of changes which may be
178 necessary.
179
181 As of 6.00, Date::Manip consists of a set of OO modules. Each have
182 their own document (see the SEE ALSO section below).
183 The OO interface consists of the following modules: Date::Manip::Date,
185 Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
186 Date::Manip::Base .
187 The object-oriented interface is the only way to get the full
189 functionality of Date::Manip. It fully support time zones (and daylight
190 saving time).
191
193 If you are running an older version of perl, the version 5 functional
194 interface is the only one available to you, and it will automatically
195 be used.
196 If you are running a newer version of perl (5.10 or higher), you can
198 use the object-oriented modules by loading them directly, or you can
199 use a functional interface.
200 If you use a functional interface, it will default to the version 6
202 interface, but you can choose to run the version 5 interface in one of
203 three ways:
204 Use the default functional interface
206 By including:
207 use Date::Manip;
209 in your script, one of the functional interfaces will be loaded.
211 If you are running a version of perl older than 5.10, it will
212 automatically be the version 5 interface. If you are running a
213 newer version of perl, it will automatically load the version 6
214 interface.
215 DATE_MANIP ENVIRONMENT VARIABLE
217 By setting the DATE_MANIP environment variable to 'DM5' before
218 running the perl script, the version 5 interface will be used.
219 Date::Manip::Backend VARIABLE
221 Alternately, you can set the Date::Manip::Backend variable to be
222 'DM5' before loading the module. Typically, this will be done in
223 the following way:
224 BEGIN {
226 $Date::Manip::Backend = 'DM5';
227 }
228 use Date::Manip;
229 Once a functional interface is loaded, you cannot switch between the
231 version 5 and version 6 interfaces.
232
234 The following documents describe various parts of Date::Manip. The
235 following documents describe the basic operation of the Date::Manip
236 package:
237 A description of the functional interfaces:
239 Date::Manip::DM5 - the version 5 functional interface
241 Date::Manip::DM6 - the version 6 functional interface
242 An introduction to the Date::Manip classes used by the object-oriented
244 interface and how to configure them:
245 Date::Manip::Objects - an overview of the various
247 Date::Manip modules, and how
248 to use them
249 Date::Manip::Config - information for configuring
250 Date::Manip
251 The methods available in each class:
253 Date::Manip::Obj - base class (modules listed below
255 inherit the methods defined in this
256 class)
257 Date::Manip::Base - module for doing low-level date
258 operations
259 Date::Manip::TZ - module for working with time zones
260 Date::Manip::Date - date operations
261 Date::Manip::Delta - delta operations
262 Date::Manip::Recur - recurrence operations
263 Timezone information:
265 Date::Manip::DM5abbrevs - time zone abbreviations used in the
267 version 5 interface
268 Date::Manip::Zones - time zone data included in Date::Manip
269 used in the version 6 interface and
270 the object-oriented interface
271 Miscellaneous information:
273 Date::Manip::Calc - date calculations
275 Date::Manip::Holidays - information on defining and using
276 holidays and events
277 Date::Manip::ConfigFile - sample config file
278 Information about the module and administrative things:
280 Date::Manip::Migration5to6
282 - information on changes necessary
283 to scripts when upgrading from
284 5.xx to 6.xx
285 Date::Manip::Changes5 - change log for Date::Manip 5.xx
286 Date::Manip::Changes5to6- differences between version 5.xx
287 and 6.00 (including information
288 on upgrading)
289 Date::Manip::Changes6 - change log for Date::Manip 6.xx
290 Date::Manip::Misc - miscellaneous information about
292 Date::Manip (who should use it;
293 acknowledgements)
294 Date::Manip::Problems - common problems and instructions
295 for reporting bugs
296 Date::Manip::Examples - examples of how to use Date::Manip
297
299 This script is free software; you can redistribute it and/or modify it
300 under the same terms as Perl itself.
301
303 Sullivan Beck (sbeck@cpan.org)
304perl v5.10.1 2011-12-07 Date::Manip(3)