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 shared by any number of objects 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 In order to achieve maximum performance, and minimize memory usage,
72 a Date::Manip::TZ object can be shared by any number of higher
73 level objects, and in fact, it is desirable to reuse the same
74 Date::Manip::TZ object as often as possible.
75 Date::Manip::Date
77 Date::Manip::Delta
78 Date::Manip::Recur
79 These are the primary modules which are used to perform all high
80 level date operations.
81 The Date::Manip::Date class performs operations on dates (which
83 includes a date, time, and time zone). The Date::Manip::Delta class
84 performs operations with deltas (amounts of time). The
85 Date::Manip::Recur class performs operations on recurring events.
86 As mentioned above, each of these high level classes rely on both a
88 Date::Manip::TZ object and a Date::Manip::Base object, so a
89 Date::Manip::TZ object is embedded in each one (and the
90 Date::Manip::TZ object has a Date::Manip::Base object embedded in
91 it).
92 A Date::Manip::Date object contains a single date, so in order to
94 work with multiple dates, multiple Date::Manip::Date objects will
95 need to be created. In order to make the most effective use of
96 cached information in the Date::Manip::Base object, the same
97 Date::Manip::TZ object can be embedded in each of the higher level
98 objects.
99 The same goes for multiple Date::Manip::Delta and
101 Date::Manip::Recur objects.
102 There are also many secondary modules including:
104 Date::Manip::TZ_Base
106 Date::Manip::TZdata
107 Date::Manip::Zones
108 Date::Manip::Lang::*
109 Date::Manip::TZ::*
110 Date::Manip::Offset::*
111 None of these are intended to be used directly.
113
115 By far the most common usage of Date::Manip involves setting a single
116 local time zone, parsing dates in a single language, and having all
117 other configuration parameters set to a single value that doesn't
118 change over the course of the program.
119 Whenever this is the case, you can use the methods listed in this
121 section to create any number of Date::Manip objects. It will
122 automatically optimize the use of cached data to get the best
123 performance.
124 If you do need to work with multiple different configurations (such as
126 parsing dates from multiple languages), please refer to the next
127 section "WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)".
128 Working with high level objects
130 The most common situation is one where you will need to use one or
131 more high level objects (Date, Delta, or Recur objects). In
132 addition, you may want to use the lower level (Base or TZ) objects.
133 The first thing you should do is to create your initial object.
135 Create the highest level object you will be using. For example if
136 you will be working with dates, create the first date object with:
137 $date = new Date::Manip::Date;
139 The next step is to set the configuration values. Use the config
141 method to do this:
142 $date->config(ARGS);
144 Although you can call the config method later, it is strongly
146 suggested that the configuration be set soon after the initial
147 object is created and not altered later. Every time you alter the
148 configuration, some of the cached data is cleared, so for optimal
149 performance, you don't want to alter the configuration if possible.
150 Additional high-level objects can be created using the calls:
152 $date2 = $date->new_date();
154 $delta = $date->new_delta();
155 $recur = $date->new_recur();
156 To access the embedded Date::Manip::TZ and Date::Manip::Base
158 objects, use the calls:
159 $tz = $date->tz();
161 $base = $date->base();
162 Working with low level objects only
164 If you will only be working with low level objects, create them
165 with one of the calls:
166 $tz = new Date::Manip::TZ;
168 $base = new Date::Manip::Base;
169 To get the base object embedded in a Date::Manip::TZ object, use:
171 $base = $tz->base();
173 For a more complete description of the methods used here, refer to the
175 Date::Manip::Obj document.
176
178 Occasionally, it may be useful to have multiple sets of configurations.
179 In order to do this, multiple Date::Manip::Base objects must be created
180 (each with their own set of configuration options), and then new
181 Date::Manip objects are created with the appropriate Date::Manip::Base
182 object embedded in them.
183 Possible reasons include:
185 Parsing multiple languages
187 A Date::Manip::Base object includes information about a single
188 language. If you need to parse dates from two (or more) languages,
189 a Date::Manip::Base object needs to be created for each one. This
190 could be done as:
191 $date_eng1 = new Date::Manip::Date;
193 $date_eng1->config("language","English");
194 $date_spa1 = new Date::Manip::Date;
196 $date_spa1->config("language","Spanish");
197 Any additional Date::Manip objects created from the first will work
199 with English. Additional objects created from the second will work
200 in Spanish.
201 Business modes for different countries and/or businesses
203 If you are doing business mode calculations (see Date::Manip::Calc)
204 for two different businesses which have different holiday lists,
205 work weeks, or business days, you can create different objects
206 which read different config files (see Date::Manip::Config) with
207 the appropriate description of each.
208 The primary issue when dealing with multiple configurations is that it
210 is necessary for the programmer to manually keep track of which
211 Date::Manip objects work with each configuration. For example, refer to
212 the following lines:
213 $date1 = new Date::Manip::Date [$opt1,$val1];
215 $date2 = new Date::Manip::Date $date1, [$opt2,$val2];
216 $date3 = new Date::Manip::Date $date1;
217 $date4 = new Date::Manip::Date $date2;
218 The first line creates 3 objects: a Date::Manip::Base object, a
220 Date::Manip::TZ object, and a Date::Manip::Date object). The
221 Date::Manip::Base object has the configuration set to contain the
222 value(s) passed in as the final list reference argument.
223 The second line creates 3 new objects (a second Date::Manip::Base
225 object, a second Date::Manip::TZ object, and a second Date::Manip::Date
226 object). Since a list reference containing config variables is passed
227 in, a new Date::Manip::Base object is created, rather than reusing the
228 first one. The second Date::Manip::Base object contains all the config
229 from the first, as well as the config variables passed in in the list
230 reference argument.
231 The third line creates another Date::Manip::Date object which uses the
233 first Date::Manip::Base and Date::Manip::TZ objects embedded in it.
234 The fourth line creates another Date::Manip::Date object which uses the
236 second Date::Manip::Base and Date::Manip::TZ objects embedded in it.
237 Most of the time there will only be one set of configuration options
239 used, so this complexity is really for a very special, and not widely
240 used, bit of functionality.
241
243 object reuse
244 In order to create additional Date::Manip objects, a previously
245 created object should be passed in as the first argument. This will
246 allow the same Base object to be embedded in both in order to
247 maximize data reuse of the cached intermediate results, and will
248 result in much better performance. For example:
249 $date1 = new Date::Manip::Date;
251 $date2 = new Date::Manip::Date $date1;
252 This is important for two reasons. First is memory usage. The
254 Date::Manip::Base object is quite large. It stores a large number
255 of precompile regular expressions for language parsing, and as date
256 operations are done, intermediate results are cached which can be
257 reused later to improve performance. The Date::Manip::TZ object is
258 even larger and contains information about all known time zones
259 indexed several different ways (by offset, by abbreviation, etc.).
260 As time zones are actually used, a description of all of the time
261 change rules are loaded and added to this object.
262 Since these objects are so large, it is important to reuse them,
264 rather than to create lots of copies of them. It should be noted
265 that because these objects are embedded in each of the high level
266 object (Date::Manip::Date for example), it makes these objects
267 appear quite large.
268 The second reason to reuse Date::Manip::Base objects is
270 performance. Since intermediate results are cached there, many date
271 operations only need to be done once and then they can be reused
272 any number of times. In essence, this is doing the same function as
273 the Memoize module, but in a more efficient manner. Memoize caches
274 results for function calls. For Date::Manip, this would often work,
275 but if you change a config variable, the return value may change,
276 so Memoize could cause things to break. In addition, Memoize caches
277 primarily at the function level, but Date::Manip stores caches
278 intermediate results wherever performance increase is seen. Every
279 time I consider caching a result, I run a test to see if it
280 increases performance. If it doesn't, or it doesn't make a
281 significant impact, I don't cache it.
282 Because the caching is quite finely tuned, it's much more efficient
284 than using a generic (though useful) tool such as Memoize.
285 configuration changes
287 As a general rule, you should only pass in configuration options
288 when the first object is created. In other words, the following
289 behavior is discouraged:
290 $date = new Date::Manip::Date;
292 $date->config(@opts);
293 ... do some stuff
295 $date->config(@opts);
297 ... do some other stuff
299 Because some of the cached results are configuration specific, when
301 a configuration change is made, some of the cached data must be
302 discarded necessitating those results to be recalculated.
303 If you really need to change configuration in the middle of
305 execution, it is certainly allowed of course, but if you can define
306 the configuration once immediately after the object is first
307 created, and then leave the configuration alone, performance will
308 be optimized.
309
311 Please refer to the Date::Manip::Problems documentation for information
312 on submitting bug reports or questions to the author.
313
315 Date::Manip - main module documentation
316
318 This script is free software; you can redistribute it and/or modify it
319 under the same terms as Perl itself.
320
322 Sullivan Beck (sbeck@cpan.org)
323perl v5.36.0 2023-03-08 Date::Manip::Objects(3)