1Date::Manip::Objects(3)User Contributed Perl DocumentatioDnate::Manip::Objects(3)
2
3
4

NAME

6       Date::Manip::Objects - A description of the various Date::Manip objects
7

SYNOPSIS

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

DESCRIPTION

14       Date::Manip consists of the following primary modules:
15
16       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
21           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
26       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
31           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
37           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
44           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
48           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
53       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
59           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
65           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
71           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
76       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
82           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
87           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
93           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
100           The same goes for multiple Date::Manip::Delta and
101           Date::Manip::Recur objects.
102
103       There are also many secondary modules including:
104
105          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
112       None of these are intended to be used directly.
113

WORKING WITH DATE::MANIP OBJECTS (SINGLE CONFIGURATION)

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
120       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
125       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
129       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
134           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
138              $date = new Date::Manip::Date;
139
140           The next step is to set the configuration values. Use the config
141           method to do this:
142
143              $date->config(ARGS);
144
145           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
151           Additional high-level objects can be created using the calls:
152
153              $date2 = $date->new_date();
154              $delta = $date->new_delta();
155              $recur = $date->new_recur();
156
157           To access the embedded Date::Manip::TZ and Date::Manip::Base
158           objects, use the calls:
159
160              $tz    = $date->tz();
161              $base  = $date->base();
162
163       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
167              $tz    = new Date::Manip::TZ;
168              $base  = new Date::Manip::Base;
169
170           To get the base object embedded in a Date::Manip::TZ object, use:
171
172              $base  = $tz->base();
173
174       For a more complete description of the methods used here, refer to the
175       Date::Manip::Obj document.
176

WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)

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
184       Possible reasons include:
185
186       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
192              $date_eng1 = new Date::Manip::Date;
193              $date_eng1->config("language","English");
194
195              $date_spa1 = new Date::Manip::Date;
196              $date_spa1->config("language","Spanish");
197
198           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
202       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
209       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
214          $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
219       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
224       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
232       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
235       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
238       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

WORKING WITH DATE::MANIP OBJECTS (ADDITIONAL NOTES)

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
250              $date1 = new Date::Manip::Date;
251              $date2 = new Date::Manip::Date $date1;
252
253           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
263           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
269           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
283           Because the caching is quite finely tuned, it's much more efficient
284           than using a generic (though useful) tool such as Memoize.
285
286       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
291               $date = new Date::Manip::Date;
292               $date->config(@opts);
293
294               ... do some stuff
295
296               $date->config(@opts);
297
298               ... do some other stuff
299
300           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
304           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

BUGS AND QUESTIONS

311       Please refer to the Date::Manip::Problems documentation for information
312       on submitting bug reports or questions to the author.
313

SEE ALSO

315       Date::Manip        - main module documentation
316

LICENSE

318       This script is free software; you can redistribute it and/or modify it
319       under the same terms as Perl itself.
320

AUTHOR

322       Sullivan Beck (sbeck@cpan.org)
323
324
325
326perl v5.36.0                      2023-03-08           Date::Manip::Objects(3)
Impressum