1Date::Manip::Obj(3) User Contributed Perl Documentation Date::Manip::Obj(3)
2
6 Date::Manip::Obj - Base class for Date::Manip objects
7
9 The Date::Manip::Obj class is the base class used for the following
10 Date::Manip classes:
11 Date::Manip::Base
13 Date::Manip::TZ
14 Date::Manip::Date
15 Date::Manip::Delta
16 Date::Manip::Recur
17 This module is not intended to be called directly and performs no
19 useful function by itself. Instead, use the various derived classes
20 which inherit from it.
21
23 This module contains a set of methods used by all Date::Manip classes
24 listed above.
25 You should be familiar with the Date::Manip::Objects and
27 Date::Manip::Config documentation.
28 In the method descriptions below, Date::Manip::Date objects will
30 usually be used as examples, but (unless otherwise stated), all of the
31 classes listed above have the same methods, and work in the same
32 fashion.
33
35 In the examples below, any $date ($date, $date1, $date2, ...) variable
36 is a Date::Manip::Date object. Similarly, $delta, $recur, $tz, and
37 $base refer to objects in the appropriate class.
38 Any $obj variable refers to an object in any of the classes.
40 new There are two ways to use the new method. They are:
42 $obj2 = new CLASS ($obj1,$string,\@opts);
44 $obj2 = $obj1->new($string,\@opts)
45 In both cases, all arguments are optional.
47 Here, CLASS is the class of the new object. For example:
49 $date = new Date::Manip::Date;
51 $delta = new Date::Manip::Delta;
52 if $obj1 is available, the new object will share as much
54 information from the old object as possible. The class of the new
55 object may be derived from the old object as well.
56 For example, if you call either of these:
58 $date2 = new Date::Manip::Date $date1;
60 $date2 = $date1->new();
61 the new date object will use the same embedded Date::Manip::TZ
63 object. In the second case, the class of the new object ($date2) is
64 Date::Manip::Date because that is the class of the original object.
65 When specifying CLASS and including an old object, objects do not
67 need to be of the same class. For example, the following are all
68 valid:
69 $date = new Date::Manip::Date $delta;
71 $date = new Date::Manip::Date $tz;
72 You can even do:
74 $date = new Date::Manip::Date $base;
76 but this will have to create a completely new Date::Manip::TZ
78 object, which means that optimal performance may not be achieved if
79 a Date::Manip::TZ object already exists.
80 There are two special cases. Either of the following will create a
82 new Date::Manip::Base object for handling multiple configurations:
83 $base2 = new Date::Manip::Base $base1;
85 $base2 = $base1->new();
86 Either of the following will create a new Date::Manip::TZ object
88 with the same Date::Manip::Base object embedded in it:
89 $tz2 = new Date::Manip::TZ $tz1;
91 $tz2 = $tz1->new();
92 The new base object will initially have the same configuration as
94 the original base object, but changing it's configuration will not
95 affect the original base object.
96 If the \@opts argument is passed in, it is a list reference
98 containing a list suitable for passing to the config method
99 (described below). In this case, a new Date::Manip::Base object
100 (and perhaps Date::Manip::TZ object) will be created. The new Base
101 object will start as identical to the original one (if a previously
102 defined object was used to create the new object) with the
103 additional options in @opts added.
104 In other words, the following are equivalent:
106 $date = new Date::Manip::Date $obj,\@opts;
108 $base = $obj->base();
110 $base2 = $base->new();
111 $date = new Date::Manip::Date $base2;
112 $date->config(@opts);
113 It should be noted that the options are applied to the NEW object,
115 not the old one. That only matters in one situation:
116 $base2 = new Date::Manip::Base $base1,\@opts;
118 $base2 = $base1->new(\@opts);
119 An optional string ($string) may be passed in only when creating a
121 Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur
122 object. If it is passed in when creating a Date::Manip::TZ or
123 Date::Manip::Base object, a warning will be issued, but execution
124 will continue.
125 If the string is included, it will be parsed to give an initial
127 value to the object. This will only be done AFTER any options are
128 handled, so the following are equivalent:
129 $date = new Date::Manip::Date $string,\@opts;
131 $date = new Date::Manip::Date;
133 $date->config(@opts);
134 $date->parse($string);
135 Note that it is generally not a good idea to pass in $string since
137 all of the parse methods allow (but do not require) additional
138 arguments, and this ability is not supported when passing in
139 $string to the new method. As a result, it's generally a better
140 practice to call the parse method separately.
141 Once a Date::Manip::Date object (or any object in any other
143 Date::Manip class) is created, it should always be used to create
144 additional objects in order to preserve cached data for optimal
145 performance and memory usage.
146 The one caveat is if you are working with multiple configurations
148 as described in the Date::Manip::Objects document. In that case,
149 you may need to create completely new objects to allow multiple
150 Date::Manip::Base objects to be used.
151 new_config
153 $obj2 = $obj1->new_config($string,\@opts);
154 This creates a new instance with a new Date::Manip::Base object
156 (and possibly a new Date::Manip::TZ object).
157 For example,
159 $date2 = $date1->new_config();
161 creates a new Date::Manip::Date object with a new Date::Manip::TZ
163 (and Date::Manip::Base) object. Initially, it is the same
164 configuration as the original object.
165 If the object is a Date::Manip::Base object, the following are
167 equivalent:
168 $base2 = $base1->new_config();
170 $base2 = $base1->new();
172 Both $string and \@opts are optional. They are used in the same way
174 they are used in the new method.
175 new_date
177 new_delta
178 new_recur
179 These are shortcuts for specifying the class. The following sets of
180 calls are all equivalent:
181 $date = $obj->new_date();
183 $date = new Date::Manip::Date($obj);
184 $delta = $obj->new_delta();
186 $delta = new Date::Manip::Date($obj);
187 These methods all allow optional ($string,\@opts) arguments.
189
191 base
192 tz
193 $base = $obj->base();
194 This returns the Date::Manip::Base object associated with the given
196 object.
197 If $obj is a Date::Manip::Base object, nothing is returned (i.e. it
199 doesn't create a new copy of the object).
200 $tz = $obj->tz();
202 This returns the Date::Manip::TZ object associated with the given
204 object. If $obj is a Date::Manip::TZ or Date::Manip::Base object,
205 nothing is returned.
206 config
208 $obj->config($var1,$val1,$var2,$val2,...);
209 This will set the value of any configuration variables. Please
211 refer to the Date::Manip::Config manual for a list of all
212 configuration variables and their description.
213 err
215 $err = $obj->err();
216 This will return the full error message if the previous operation
218 failed for any reason.
219 $obj->err(1);
221 will clear the error code.
223 is_date
225 is_delta
226 is_recur
227 $flag = $obj->is_date();
228 Returns 0 or 1, depending on the object. For example, a
230 Date::Manip::Date object returns 1 with the is_date method, and 0
231 for the other two.
232 version
234 $vers = $obj->version($flag);
235 This returns the version of Date::Manip.
237 If $flag is passed in, and $obj is not a Date::Manip::Base object,
239 the version and timezone information will be passed back.
240
242 None known.
243
245 Please refer to the Date::Manip::Problems documentation for information
246 on submitting bug reports or questions to the author.
247
249 Date::Manip - main module documentation
250
252 This script is free software; you can redistribute it and/or modify it
253 under the same terms as Perl itself.
254
256 Sullivan Beck (sbeck@cpan.org)
257perl v5.10.1 2011-12-07 Date::Manip::Obj(3)