Date::Manip::Obj(3pm)

1Date::Manip::Obj(3)   User Contributed Perl Documentation  Date::Manip::Obj(3)
2
3
4

NAME

6       Date::Manip::Obj - Base class for Date::Manip objects
7

SYNOPSIS

9       The Date::Manip::Obj class is the base class used for the following
10       Date::Manip classes:
11
12       Date::Manip::Base
13       Date::Manip::TZ
14       Date::Manip::Date
15       Date::Manip::Delta
16       Date::Manip::Recur
17
18       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

DESCRIPTION

23       This module contains a set of methods used by all Date::Manip classes
24       listed above.
25
26       You should be familiar with the Date::Manip::Objects and
27       Date::Manip::Config documentation.
28
29       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

METHODS FOR CREATING OBJECTS

35       In the examples below, any variable named some variation of $date
36       ($date, $date1, $date2, ...) is a Date::Manip::Date object. Similarly,
37       $delta, $recur, $tz, and $base refer to objects in the appropriate
38       class.
39
40       Any $obj variable refers to an object in any of the classes.
41
42       new There are two ways to use the new method. They are:
43
44              $obj2  = new CLASS ($obj1,$string,@parse_opts,\@opts);
45              $obj2  = $obj1->new($string,@parse_opts,\@opts)
46
47           In both cases, all arguments are optional.
48
49           Both methods are used to create a new object of a given class.  In
50           the first case, CLASS is the class of the new object. For example:
51
52              $date  = new Date::Manip::Date;
53              $delta = new Date::Manip::Delta;
54
55           In the second method, the class of the new object will be derived
56           from the first object.  For example:
57
58              $date1 = new Date::Manip::Date;
59              $date2 = $date1->new();
60
61           the class of the second object ($date2) is Date::Manip::Date
62           because that is the class of the object ($date1) used to create it.
63
64           In both first method (when a $obj1 is passed in) and always in the
65           second method, the new object will share as much information from
66           the old object ($obj1) as possible.
67
68           For example, if you call either of these:
69
70              $date2 = new Date::Manip::Date $date1;
71              $date2 = $date1->new();
72
73           the new date object will use the same embedded Date::Manip::TZ and
74           Date::Manip::Base objects.
75
76           When specifying CLASS and including an old object, objects do not
77           need to be of the same class.  For example, the following are all
78           valid:
79
80              $date = new Date::Manip::Date $delta;
81              $date = new Date::Manip::Date $tz;
82
83           You can even do:
84
85              $date = new Date::Manip::Date $base;
86
87           but this will have to create a completely new Date::Manip::TZ
88           object, which means that optimal performance may not be achieved if
89           a Date::Manip::TZ object already exists.
90
91           There are two special cases. Either of the following will create a
92           new Date::Manip::Base object for handling multiple configurations:
93
94              $base2 = new Date::Manip::Base $base1;
95              $base2 = $base1->new();
96
97           Either of the following will create a new Date::Manip::TZ object
98           with the same Date::Manip::Base object embedded in it:
99
100              $tz2   = new Date::Manip::TZ $tz1;
101              $tz2   = $tz1->new();
102
103           The new base object will initially have the same configuration as
104           the original base object, but changing it's configuration will not
105           affect the original base object.
106
107           If the "\@opts" argument is passed in, it is a list reference
108           containing a list suitable for passing to the config method
109           (described below). In this case, a new Date::Manip::Base object
110           (and perhaps Date::Manip::TZ object) will be created. The new Base
111           object will start as identical to the original one (if a previously
112           defined object was used to create the new object) with the
113           additional options in @opts added.
114
115           In other words, the following are equivalent:
116
117              $date  = new Date::Manip::Date $obj,\@opts;
118
119              $base  = $obj->base();
120              $base2 = $base->new();
121              $date = new Date::Manip::Date $base2;
122              $date->config(@opts);
123
124           It should be noted that the options are applied to the NEW
125           Date::Manip::Base object, not the old one.
126
127           An optional string ($string and parse opts @parse_opts) may be
128           passed in only when creating a Date::Manip::Date,
129           Date::Manip::Delta, or Date::Manip::Recur object.  If passed in
130           when creating a Date::Manip::TZ or Date::Manip::Base object, a
131           warning will be issued, but execution will continue.
132
133           If the string is included, it will be parsed to give an initial
134           value to the object. This will only be done AFTER any options are
135           handled, so the following are equivalent:
136
137              $date = new Date::Manip::Date $string,@parse_opts,\@opts;
138
139              $date = new Date::Manip::Date;
140              $date->config(@opts);
141              $date->parse($string,@parse_opts);
142
143           Once a Date::Manip::Date object (or any object in any other
144           Date::Manip class) is created, it should always be used to create
145           additional objects in order to preserve cached data for optimal
146           performance and memory usage.
147
148           The one caveat is if you are working with multiple configurations
149           as described in the Date::Manip::Objects document. In that case,
150           you may need to create completely new objects to allow multiple
151           Date::Manip::Base objects to be used.
152
153       new_config
154              $obj2 = $obj1->new_config($string,\@opts);
155
156           This creates a new instance with a new Date::Manip::Base object
157           (and possibly a new Date::Manip::TZ object).
158
159           For example,
160
161              $date2 = $date1->new_config();
162
163           creates a new Date::Manip::Date object with a new Date::Manip::TZ
164           (and Date::Manip::Base) object. Initially, it is the same
165           configuration as the original object.
166
167           If the object is a Date::Manip::Base object, the following are
168           equivalent:
169
170              $base2 = $base1->new_config();
171
172              $base2 = $base1->new();
173
174           Both $string and "\@opts" are optional. They are used in the same
175           way they are used in the new method.
176
177       new_date
178       new_delta
179       new_recur
180           These are shortcuts for specifying the class. The following sets of
181           calls are all equivalent:
182
183              $date  = $obj->new_date();
184              $date  = new Date::Manip::Date($obj);
185
186              $delta = $obj->new_delta();
187              $delta = new Date::Manip::Date($obj);
188
189           These methods all allow optional "($string,\@opts)" arguments.
190

OTHER METHODS

192       base
193       tz
194              $base = $obj->base();
195
196           This returns the Date::Manip::Base object associated with the given
197           object.
198
199           If $obj is a Date::Manip::Base object, nothing is returned (i.e. it
200           doesn't create a new copy of the object).
201
202              $tz = $obj->tz();
203
204           This returns the Date::Manip::TZ object associated with the given
205           object. If $obj is a Date::Manip::TZ or Date::Manip::Base object,
206           nothing is returned.
207
208       config
209              $obj->config($var1,$val1,$var2,$val2,...);
210
211           This will set the value of any configuration variables. Please
212           refer to the Date::Manip::Config manual for a list of all
213           configuration variables and their description.
214
215       get_config
216              @var = $obj->get_config();
217              $val = $obj->get_config($var1);
218              @val = $obj->get_config($var1,$var2,...);
219
220           This queries the current config values.  With no argument, it will
221           return the list of config variables (all lowercase).
222
223           With one or more arguments, it returns the current values for the
224           config variables passed in (case insensitive).
225
226       err
227              $err = $obj->err();
228
229           This will return the full error message if the previous operation
230           failed for any reason.
231
232              $obj->err(1);
233
234           will clear the error code.
235
236       is_date
237       is_delta
238       is_recur
239              $flag = $obj->is_date();
240
241           Returns 0 or 1, depending on the object. For example, a
242           Date::Manip::Date object returns 1 with the is_date method, and 0
243           for the other two.
244
245       version
246              $vers = $obj->version($flag);
247
248           This returns the version of Date::Manip.
249
250           If $flag is passed in, and $obj is not a Date::Manip::Base object,
251           the version and timezone information will be passed back.
252

KNOWN BUGS

254       None known.
255

BUGS AND QUESTIONS

257       Please refer to the Date::Manip::Problems documentation for information
258       on submitting bug reports or questions to the author.
259

LICENSE

264       This script is free software; you can redistribute it and/or modify it
265       under the same terms as Perl itself.
266

AUTHOR

268       Sullivan Beck (sbeck@cpan.org)
269
270
271
272perl v5.38.0                      2023-07-20               Date::Manip::Obj(3)