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 type of information. This
11 document describes how the various modules work together.
12
14 Date::Manip consists of several different modules, each of which deal
15 with a different type of data.
16 The primary modules are:
18 Date::Manip::Obj
20 The Date::Manip::Obj module is not intended for direct use. It is
21 used as a base class for all other Date::Manip classes described
22 below.
23 The Date::Manip::Obj module contains some functions which are
25 inherited by all these classes, so to understand all of the methods
26 available to any of the classes below, you must include those
27 documented in the Date::Manip::Obj class.
28 Date::Manip::Base
30 The Date::Manip::Base is used to perform basic operations including
31 basic date operations, management of configuration options,
32 handling the definitions used in different languages, etc.
33 A Date::Manip::Base object does not, of itself, contain any date
35 information. Instead, it contains configuration information which
36 determines how the Date::Manip package performs date operations.
37 The configuration information is documented in the
38 Date::Manip::Config manual.
39 The Date::Manip::Base object has one other property that is very
41 important. When performing basic date properties, some intermediate
42 results are cached in the object which leads to significant
43 performance increases in later operations. As such, it is important
44 to reuse the object as much as possible, rather than creating new
45 Date::Manip::Base objects all the time.
46 Much of the information in this document is related to this issue,
48 and tells how to create various objects in order to get the most
49 efficient reuse of this cached data.
50 Because all other objects depend on a Date::Manip::Base object, a
52 Date::Manip::Base object is embedded in all other objects, and the
53 same Base object can be embedded as often as desired to achieve
54 maximum performance.
55 Date::Manip::TZ
57 The Date::Manip::TZ module adds support for time zones. It is used
58 to verify date and time zone information, convert dates from one
59 time zone to another, and handle all daylight saving time
60 transitions.
61 All higher level objects (those listed next) depend on both a
63 Date::Manip::Base and Date::Manip::TZ object, so one of each are
64 embedded into those objects.
65 Date::Manip::Date
67 Date::Manip::Delta
68 Date::Manip::Recur
69 These are the primary modules which are used to perform all high
70 level date operations.
71 The Date::Manip::Date class performs operations on dates (which
73 includes a date, time, and time zone). The Date::Manip::Delta class
74 performs operations with deltas (amounts of time). The
75 Date::Manip::Recur class performs operations on recurring events.
76 As mentioned above, each of these high level classes rely on both a
78 Date::Manip::TZ object and a Date::Manip::Base object, and one of
79 each is embedded in each object.
80 A Date::Manip::Date object contains a single date, so in order to
82 work with multiple dates, multiple Date::Manip::Date objects will
83 need to be created. In order to make the most effective use of
84 cached information in the Date::Manip::Base object, the same
85 Date::Manip::Base object can be embedded in each of the higher
86 level objects.
87 The same goes for multiple Date::Manip::Delta and
89 Date::Manip::Recur objects.
90
92 The basic way to create the first instance of a Date::Manip object (of
93 any class) is to use the "new" method of the appropriate class. This
94 is documented in the Date::Manip::Obj manual. For example:
95 $tz = new Date::Manip::TZ;
97 $date = new Date::Manip::Date;
98 Optionally, config options can be passed in:
100 $tz = new Date::Manip::TZ \@opts;
102 $date = new Date::Manip::Date \@opt;
103 In order to create additional Date::Manip objects, a previously created
105 object should be passed in as the first argument. This will allow the
106 same Base object to be embedded in both in order to maximize data reuse
107 of the cached intermediate results, and will result in much better
108 performance. For example:
109 $date1 = new Date::Manip::Date;
111 $date2 = new Date::Manip::Date $date1;
112 As a general rule, you should only pass in configuration options when
114 the first object is created. In other words, the following behavior:
115 $date1 = new Date::Manip::Date [$opt1,$val1,$opt2,$val2];
117 $date2 = new Date::Manip::Date $date1;
118 will behave differently than:
120 $date1 = new Date::Manip::Date [$opt1,$val1];
122 $date2 = new Date::Manip::Date $date1,[$opt2,$val2];
123 In the first case, only a single Date::Manip::Base object is created.
125 In the second case, two Date::Manip::Base objects are created.
126 Unless you specifically need to work with multiple sets of
128 configurations (which is described below), it is far less complicated,
129 and results in better performance, to work with only a single
130 Date::Manip::Base object.
131 It is also preferred that all configuration be done soon after the
133 first object is created in order to keep things clear.
134 To following example illustrates a potential pitfall:
136 $date1 = new Date::Manip::Date [$opt1,$val1];
138 $date2 = new Date::Manip::Date $date1,
139 $date1->config($opt2,$val2);
140 The first two lines create a total of 4 Date::Manip object. The first
142 line creates a Date::Manip::Base object and a Date::Manip::TZ object,
143 and then a Date::Manip::Date object with the first two embedded in it.
144 The second line creates a second Date::Manip::Date object, with the
146 same Date::Manip::Base and Date::Manip::TZ objects embedded in it.
147 The third line alters the configuration information used by the $date1
149 object. Since configuration information is stored only in the Base
150 object, that object is modified, and therefore, the configuration
151 change impacts both $date1 and $date2 objects (and any additional
152 Date::Manip objects created from either of them).
153 In order to keep things clean, it is highly recommended that the above
155 example be reordered:
156 $date1 = new Date::Manip::Date [$opt1,$val1];
158 $date1->config($opt2,$val2);
159 $date2 = new Date::Manip::Date $date1,
160 and all configuration changes be made immediately after (or as close to
162 it as possible) the creation of the first object.
163
165 Occasionally, it may be useful to have multiple sets of configurations.
166 In order to do this, multiple Date::Manip::Base objects must be created
167 (each with their own set of configuration options), and then new
168 Date::Manip objects are created with the appropriate Date::Manip::Base
169 object embedded in them.
170 Possible reasons include:
172 Parsing multiple languages
174 A Date::Manip::Base object includes information about a single
175 language. If you need to parse dates from two (or more) languages,
176 a Date::Manip::Base object needs to be created for each one. This
177 could be done as:
178 $date_eng1 = new Date::Manip::Date ["language","English"];
180 $date_spa1 = new Date::Manip::Date $date_eng1,["language","Spanish"];
181 Any additional Date::Manip objects created from the first will work
183 with English. Additional objects created from the second will work
184 in Spanish.
185 Business modes for different countries and/or businesses
187 If you are doing business mode calculations (see Date::Manip::Calc)
188 for two different businesses which have different holiday lists,
189 work weeks, or business days, you can create different objects
190 which read different config files (see Date::Manip::Config) with
191 the appropriate description of each.
192 The primary issue when dealing with multiple configurations is that it
194 is necessary for the programmer to manually keep track of which
195 Date::Manip objects work with each configuration. For example, refer to
196 the following lines:
197 $date1 = new Date::Manip::Date [$opt1,$val1];
199 $date2 = new Date::Manip::Date $date1, [$opt2,$val2];
200 $date3 = new Date::Manip::Date $date1;
201 $date4 = new Date::Manip::Date $date2;
202 The first line creates 3 objects (a Date::Manip::Base object, a
204 Date::Manip::TZ object, and a Date::Manip::Date object). The
205 Date::Manip::Base object has the configuration set to contain the
206 value(s) passed in as the final list reference argument.
207 The second line creates 3 new objects (a second Date::Manip::Base
209 object, a second Date::Manip::TZ object, and a second Date::Manip::Date
210 object). Since a list reference containing config variables is passed
211 in, a new Date::Manip::Base object is created, rather than reusing the
212 first one. The second Date::Manip::Base object contains all the config
213 from the first, as well as the config variables passed in in the list
214 reference argument.
215 The third line creates another Date::Manip::Date object which uses the
217 first Date::Manip::Base and Date::Manip::TZ objects embedded in it.
218 The fourth line creates another Date::Manip::Date object which uses the
220 second Date::Manip::Base and Date::Manip::TZ objects embedded in it.
221 Luckily, most of the time there will only be one set of configuration
223 options used, so this complexity is really for a very special, and not
224 widely used, bit of functionality.
225
227 If you are working with any higher level Date::Manip modules
228 (Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur), you
229 probably will not need to work with the lower Date::Manip::Base and
230 Date::Manip::TZ objects directly. However, if you want to make use of
231 some of the faster Date::Manip::Base operations, or work directly with
232 time zones, you can access the lower level objects using the "base" and
233 "tz" methods from the higher level object.
234 More information is in the Date::Manip::Obj manual.
236
238 Please refer to the Date::Manip::Problems documentation for information
239 on submitting bug reports or questions to the author.
240
242 Date::Manip - main module documentation
243
245 This script is free software; you can redistribute it and/or modify it
246 under the same terms as Perl itself.
247
249 Sullivan Beck (sbeck@cpan.org)
250perl v5.12.0 2010-04-27 Date::Manip::Objects(3)