1Date::Manip::Objects(3)User Contributed Perl DocumentatioDnate::Manip::Objects(3)
2
6 Date::Manip::Objects - A description of the various Date::Manip objects
7
9 The Date::Manip package consist of several modules, each of which
10 perform a set of operations on a specific class of objects. This
11 document describes how the various modules work together.
12
14 Date::Manip consists of the following primary modules:
15 Date::Manip::Obj
17 The Date::Manip::Obj module is not intended for direct use. It is
18 used as a base class for all other Date::Manip classes described
19 below.
20 The Date::Manip::Obj module contains some functions which are
22 inherited by all these classes, so to understand all of the methods
23 available to any of the classes below, you must include those
24 documented in the Date::Manip::Obj class.
25 Date::Manip::Base
27 The Date::Manip::Base is used to perform basic operations including
28 basic date operations, management of configuration options,
29 handling the definitions used in different languages, etc.
30 A Date::Manip::Base object does not, of itself, contain any date
32 information. Instead, it contains configuration information which
33 determines how the Date::Manip package performs date operations.
34 The configuration information is documented in the
35 Date::Manip::Config document.
36 The Date::Manip::Base object has one other property that is very
38 important. When performing basic date operations, some intermediate
39 results are cached in the object which leads to significant
40 performance increases in later operations. As such, it is important
41 to reuse the object as much as possible, rather than creating new
42 Date::Manip::Base objects all the time.
43 Much of the information in this document is related to this issue,
45 and tells how to create various higher-level objects in order to
46 get the most efficient reuse of this cached data.
47 Because all other objects depend on a Date::Manip::Base object, a
49 Date::Manip::Base object is embedded in all other objects, and the
50 same Base object can be embedded as often as desired to achieve
51 maximum performance.
52 Date::Manip::TZ
54 The Date::Manip::TZ module adds support for time zones. It is used
55 to verify date and time zone information, convert dates from one
56 time zone to another, and handle all daylight saving time
57 transitions.
58 Similar to the Date::Manip::Base object, a great deal of
60 information is cached in the Date::Manip::TZ object. This includes
61 lists of all time zones, offsets, and abbreviations for all time
62 zones. It also includes more a more detailed description of every
63 time zone that has actually been worked used.
64 A Date::Manip::TZ object relies on a Date::Manip::Base object (and
66 a Date::Manip::Base object is always embedded in a Date::Manip::TZ
67 object). All higher level objects (those listed next) depend on
68 both a Date::Manip::Base and Date::Manip::TZ object, so a
69 Date::Manip::TZ object is embedded in them.
70 Date::Manip::Date
72 Date::Manip::Delta
73 Date::Manip::Recur
74 These are the primary modules which are used to perform all high
75 level date operations.
76 The Date::Manip::Date class performs operations on dates (which
78 includes a date, time, and time zone). The Date::Manip::Delta class
79 performs operations with deltas (amounts of time). The
80 Date::Manip::Recur class performs operations on recurring events.
81 As mentioned above, each of these high level classes rely on both a
83 Date::Manip::TZ object and a Date::Manip::Base object, so a
84 Date::Manip::TZ object is embedded in each one (and the
85 Date::Manip::TZ object has a Date::Manip::Base object embedded in
86 it).
87 A Date::Manip::Date object contains a single date, so in order to
89 work with multiple dates, multiple Date::Manip::Date objects will
90 need to be created. In order to make the most effective use of
91 cached information in the Date::Manip::Base object, the same
92 Date::Manip::TZ object can be embedded in each of the higher level
93 objects.
94 The same goes for multiple Date::Manip::Delta and
96 Date::Manip::Recur objects.
97 There are also many secondary modules including:
99 Date::Manip::TZ_Base
101 Date::Manip::TZdata
102 Date::Manip::Zones
103 Date::Manip::Lang::*
104 Date::Manip::TZ::*
105 Date::Manip::Offset::*
106 None of these are intended to be used directly.
108
110 By far the most common usage of Date::Manip involves setting a single
111 local time zone, parsing dates in a single language, and having all
112 other configuration parameters set to a single value that doesn't
113 change over the course of the program.
114 Whenever this is the case, you can use the methods listed in this
116 section to create any number of Date::Manip objects. It will
117 automatically optimize the use of cached data to get the best
118 performance.
119 If you do need to work with multiple different configurations (such as
121 parsing dates from multiple languages), please refer to the next
122 section WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATIONS).
123 Working with high level objects
125 The most common situation is one where you will need to use one or
126 more high level objects (Date, Delta, or Recur objects). In
127 addition, you may want to use the lower level (Base or TZ) objects.
128 The first thing you should do is to create your initial object.
130 Create the highest level object you will be using. For example if
131 you will be working with dates, create the first date object with:
132 $date = new Date::Manip::Date;
134 The next step is to set the configuration values. Use the config
136 method to do this:
137 $date->config(ARGS);
139 Although you can call the config method later, it is strongly
141 suggested that the configuration be set soon after the initial
142 object is created and not altered later. Every time you alter the
143 configuration, some of the cached data is cleared, so for optimal
144 performance, you don't want to alter the configuration if possible.
145 Additional high-level objects can be created using the calls:
147 $date2 = $date->new_date();
149 $delta = $date->new_delta();
150 $recur = $date->new_recur();
151 To access the embedded Date::Manip::TZ and Date::Manip::Base
153 objects, use the calls:
154 $tz = $date->tz();
156 $base = $date->base();
157 Working with low level objects only
159 If you will only be working with low level objects, create them
160 with one of the calls:
161 $tz = new Date::Manip::TZ;
163 $base = new Date::Manip::Base;
164 To get the base object embedded in a Date::Manip::TZ object, use:
166 $base = $tz->base();
168 For a more complete description of the methods used here, refer to the
170 Date::Manip::Obj document.
171
173 Occasionally, it may be useful to have multiple sets of configurations.
174 In order to do this, multiple Date::Manip::Base objects must be created
175 (each with their own set of configuration options), and then new
176 Date::Manip objects are created with the appropriate Date::Manip::Base
177 object embedded in them.
178 Possible reasons include:
180 Parsing multiple languages
182 A Date::Manip::Base object includes information about a single
183 language. If you need to parse dates from two (or more) languages,
184 a Date::Manip::Base object needs to be created for each one. This
185 could be done as:
186 $date_eng1 = new Date::Manip::Date;
188 $date_eng1->config("language","English");
189 $date_spa1 = new Date::Manip::Date;
191 $date_spa1->config("language","Spanish");
192 Any additional Date::Manip objects created from the first will work
194 with English. Additional objects created from the second will work
195 in Spanish.
196 Business modes for different countries and/or businesses
198 If you are doing business mode calculations (see Date::Manip::Calc)
199 for two different businesses which have different holiday lists,
200 work weeks, or business days, you can create different objects
201 which read different config files (see Date::Manip::Config) with
202 the appropriate description of each.
203 The primary issue when dealing with multiple configurations is that it
205 is necessary for the programmer to manually keep track of which
206 Date::Manip objects work with each configuration. For example, refer to
207 the following lines:
208 $date1 = new Date::Manip::Date [$opt1,$val1];
210 $date2 = new Date::Manip::Date $date1, [$opt2,$val2];
211 $date3 = new Date::Manip::Date $date1;
212 $date4 = new Date::Manip::Date $date2;
213 The first line creates 3 objects: a Date::Manip::Base object, a
215 Date::Manip::TZ object, and a Date::Manip::Date object). The
216 Date::Manip::Base object has the configuration set to contain the
217 value(s) passed in as the final list reference argument.
218 The second line creates 3 new objects (a second Date::Manip::Base
220 object, a second Date::Manip::TZ object, and a second Date::Manip::Date
221 object). Since a list reference containing config variables is passed
222 in, a new Date::Manip::Base object is created, rather than reusing the
223 first one. The second Date::Manip::Base object contains all the config
224 from the first, as well as the config variables passed in in the list
225 reference argument.
226 The third line creates another Date::Manip::Date object which uses the
228 first Date::Manip::Base and Date::Manip::TZ objects embedded in it.
229 The fourth line creates another Date::Manip::Date object which uses the
231 second Date::Manip::Base and Date::Manip::TZ objects embedded in it.
232 Most of the time there will only be one set of configuration options
234 used, so this complexity is really for a very special, and not widely
235 used, bit of functionality.
236
238 object reuse
239 In order to create additional Date::Manip objects, a previously
240 created object should be passed in as the first argument. This will
241 allow the same Base object to be embedded in both in order to
242 maximize data reuse of the cached intermediate results, and will
243 result in much better performance. For example:
244 $date1 = new Date::Manip::Date;
246 $date2 = new Date::Manip::Date $date1;
247 This is important for two reasons. First is memory usage. The
249 Date::Manip::Base object is quite large. It stores a large number
250 of precompile regular expressions for language parsing, and as date
251 operations are done, intermediate results are cached which can be
252 reused later to improve performance. The Date::Manip::TZ object is
253 even larger and contains information about all known time zones
254 indexed several different ways (by offset, by abbreviation, etc.).
255 As time zones are actually used, a description of all of the time
256 change rules are loaded and added to this object.
257 Since these objects are so large, it is important to reuse them,
259 rather than to create lots of copies of them. It should be noted
260 that because these objects are embedded in each of the high level
261 object (Date::Manip::Date for example), it makes these objects
262 appear quite large.
263 The second reason to reuse Date::Manip::Base objects is
265 performance. Since intermediate results are cached there, many date
266 operations only need to be done once and then they can be reused
267 any number of times. In essence, this is doing the same function as
268 the Memoize module, but in a more efficient manner. Memoize caches
269 results for function calls. For Date::Manip, this would often work,
270 but if you change a config variable, the return value may change,
271 so Memoize could cause things to break. In addition, Memoize caches
272 primarily at the function level, but Date::Manip stores caches
273 intermediate results wherever performance increase is seen. Every
274 time I consider caching a result, I run a test to see if it
275 increases performance. If it doesn't, or it doesn't make a
276 significant impact, I don't cache it.
277 Because the caching is quite finely tuned, it's much more efficient
279 than using a generic (though useful) tool such as Memoize.
280 configuration changes
282 As a general rule, you should only pass in configuration options
283 when the first object is created. In other words, the following
284 behavior is discouraged:
285 $date = new Date::Manip::Date;
287 $date->config(@opts);
288 ... do some stuff
290 $date->config(@opts);
292 ... do some other stuff
294 Because some of the cached results are configuration specific, when
296 a configuration change is made, some of the cached data must be
297 discarded necessitating those results to be recalculated.
298 If you really need to change configuration in the middle of
300 execution, it is certainly allowed of course, but if you can define
301 the configuration once immediately after the object is first
302 created, and then leave the configuration alone, performance will
303 be optimized.
304
306 Please refer to the Date::Manip::Problems documentation for information
307 on submitting bug reports or questions to the author.
308
310 Date::Manip - main module documentation
311
313 This script is free software; you can redistribute it and/or modify it
314 under the same terms as Perl itself.
315
317 Sullivan Beck (sbeck@cpan.org)
318perl v5.10.1 2011-12-07 Date::Manip::Objects(3)