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, determining a data 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. Most
44 people will think of a delta as an amount of time, but the term
45 'time' is already used so much in this module that I didn't want to
46 use it here in order to avoid confusion.
47 recurrence
49 A recurring event is something which occurs on a regular recurring
50 basis.
51 holidays and events
53 Holidays and events are basically named dates or recurrences.
54 Among other things, Date::Manip allow you to:
56 * Enter a date in practically any format you choose.
58 * Compare two dates, entered in widely different formats to determine
60 which is earlier.
61 * Extract any information you want from a date using a format string
63 similar to the Unix date command.
64 * Determine the amount of time between two dates, or add an amount of
66 time to a date to get a second date.
67 * Work with dates with dates using international formats (foreign
69 month names, 12/10/95 referring to October rather than December,
70 etc.).
71 * To find a list of dates where a recurring event happens.
73 Each of these tasks is trivial (one or two lines at most) with this
75 package.
76
78 Date::Manip version 6.00 was a complete rewrite of the module (for more
79 information, please refer to the Date::Manip::Changes5to6 document).
80 The rewrite made use of features introduced in perl 5.10 which made the
81 date parsing routines significantly more robust. However, since not
82 everyone has access to a new version of perl where Date::Manip is
83 needed, the Date::Manip distribution actually includes two different
84 versions of the module. It includes the older (5.xx) release and the
85 newer (6.xx) release.
86 In addition, the 6.xx release was written with both a functional and an
88 object-oriented interface, so there are actually three different ways
89 to use Date::Manip (though only one is available if you have a version
90 of perl older than 5.10).
91 For those who still run an older version of perl, the 5.xx functional
93 interface is still available. It is known to work with perl 5.6 (and
94 probably works with even older versions of perl). There are some
95 limitations to this as described below.
96 Version 6.xx was rewritten as a series of object-oriented modules, but
98 a functional interface (which is mostly backward compatible with the
99 version 5 functional interface) is included. The functional interface
100 is simply wrapper functions which call the OO modules.
101 A more detailed description of each interface is included below (to
103 help you decide which interface is right for you). If you already know
104 which interface you want to use, just go to the SEE ALSO section below
105 for instructions on using each interface.
106 It should be noted that all three interfaces will be installed, but
108 they will only all be usable with a recent version of perl.
109
111 When using a version of perl older than 5.10, this is the only
112 interface available. This interface is documented in the
113 Date::Manip::DM5 document. This interface has several weaknesses that
114 need to be understood when using it:
115 Limited Support
117 The version 5 functional interface is no longer being developed,
118 and only limited support is available for it.
119 As of December 2012, no development will be done, and I will not
121 correct any remaining bugs in version 5. If a patch is supplied by
122 someone else to fix bugs, I will apply it, provided it applies
123 cleanly, and the resulting code continues to pass all tests. I
124 will not apply patches to add features.
125 I will continue to distribute version 5 for several years. I do
127 not have a date in mind where version 5 will be removed.
128 Limited Time Zone Support
130 Time zone support is extremely limited, and is often broken. The
131 lack of good time zone support was the primary reason for rewriting
132 Date::Manip .
133 Time zone information for 5.xx is now automatically generated from
135 the 6.xx time zone list, and every time time zones are updated in
136 6.xx, the 5.xx release will be similarly updated.
137 Prior to the release of 6.00, time zones were added manually to
139 Date::Manip upon request. Since time zone information in 5.xx is
140 now automatically generated, I no longer take requests for time
141 zones.
142 The version 5 interface does not handle daylight saving time
144 changes properly.
145 Performance Issues
147 Considerable time has been spent speeding up Date::Manip, and
148 fairly simple benchmarks show that version 6 is around twice as
149 fast as version 5.
150 Feel free to email me concerns and comments.
152
154 The version 6 functional interface is almost completely identical to
155 the version 5 functional interface, except that it uses the object-
156 oriented modules to do all the real work.
157 Time zone support is greatly improved, but is still somewhat limited.
159 Since the version 6 interface is backward compatible, dates do not
160 store time zone information in them, so the programmer is responsible
161 for keeping track of what time zone each date is in. If you want full
162 access to the time zone support offered in Date::Manip, you have to use
163 the object-oriented interface.
164 For the most part, scripts written for older versions of Date::Manip
166 will continue to work (and scripts written for the version 6 functional
167 interface will run with the version 5 interface), however in a few
168 cases, you may need to modify your scripts. Please refer to the
169 Date::Manip::Migration5to6 document for a list of changes which may be
170 necessary.
171
173 As of 6.00, Date::Manip consists of a set of OO modules. Each have
174 their own document (see the SEE ALSO section below).
175 The OO interface consists of the following modules: Date::Manip::Date,
177 Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
178 Date::Manip::Base .
179 The object-oriented interface is the only way to get the full
181 functionality of Date::Manip. It fully support time zones (and daylight
182 saving time).
183
185 If you are running an older version of perl, the version 5 functional
186 interface is the only one available to you, and it will automatically
187 be used.
188 If you are running a newer version of perl (5.10 or higher), you can
190 use the object-oriented modules by loading them directly, or you can
191 use a functional interface.
192 If you use a functional interface, it will default to the version 6
194 interface, but you can choose to run the version 5 interface in one of
195 three ways:
196 Use the default functional interface
198 By including:
199 use Date::Manip;
201 in your script, one of the functional interfaces will be loaded.
203 If you are running a version of perl older than 5.10, it will
204 automatically be the version 5 interface. If you are running a
205 newer version of perl, it will automatically load the version 6
206 interface.
207 DATE_MANIP ENVIRONMENT VARIABLE
209 By setting the DATE_MANIP environment variable to 'DM5' before
210 running the perl script, the version 5 interface will be used.
211 Date::Manip::Backend VARIABLE
213 Alternately, you can set the Date::Manip::Backend variable to be
214 'DM5' before loading the module. Typically, this will be done in
215 the following way:
216 BEGIN {
218 $Date::Manip::Backend = 'DM5';
219 }
220 use Date::Manip;
221 Once a functional interface is loaded, you cannot switch between the
223 version 5 and version 6 interfaces.
224
226 The following documents describe various parts of Date::Manip. The
227 following documents describe the basic operation of the Date::Manip
228 package:
229 A description of the functional interfaces:
231 Date::Manip::DM5 - the version 5 functional interface
233 Date::Manip::DM6 - the version 6 functional interface
234 An introduction to the Date::Manip classes used by the object-oriented
236 interface and how to configure them:
237 Date::Manip::Objects - an overview of the various
239 Date::Manip modules, and how
240 to use them
241 Date::Manip::Config - information for configuring
242 Date::Manip
243 The methods available in each class:
245 Date::Manip::Obj - base class (modules listed below
247 inherit the methods defined in this
248 class)
249 Date::Manip::Base - module for doing low-level date
250 operations
251 Date::Manip::TZ - module for working with time zones
252 Date::Manip::Date - date operations
253 Date::Manip::Delta - delta operations
254 Date::Manip::Recur - recurrence operations
255 Timezone information:
257 Date::Manip::DM5abbrevs - time zone abbreviations used in the
259 version 5 interface
260 Date::Manip::Zones - time zone data included in Date::Manip
261 used in the version 6 interface and
262 the object-oriented interface
263 Miscellaneous information:
265 Date::Manip::Calc - detailed informaion on how date
267 calculations are done
268 Date::Manip::Holidays - information on defining and using
269 holidays and events
270 Date::Manip::ConfigFile - sample config file
271 Date::Manip::Lang - information about the languages
272 supported by Date::Manip and how
273 to add a new language
274 Information about the module and administrative things:
276 Date::Manip::Migration5to6
278 - information on changes necessary
279 to scripts when upgrading from
280 5.xx to 6.xx
281 Date::Manip::Changes5 - change log for Date::Manip 5.xx
282 Date::Manip::Changes5to6- differences between version 5.xx
283 and 6.00 (including information
284 on upgrading); this contains more
285 details than the Migration5to6
286 document
287 Date::Manip::Changes6 - change log for Date::Manip 6.xx
288 Date::Manip::Misc - miscellaneous information about
290 Date::Manip (who should use it;
291 acknowledgements)
292 Date::Manip::Problems - common problems and instructions
293 for reporting bugs
294 Date::Manip::Examples - examples of how to use Date::Manip
295
297 This script is free software; you can redistribute it and/or modify it
298 under the same terms as Perl itself.
299
301 Sullivan Beck (sbeck@cpan.org)
302perl v5.16.3 2014-06-09 Date::Manip(3)