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 $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
39       Any $obj variable refers to an object in any of the classes.
40
41       new There are two ways to use the new method. They are:
42
43              $obj2  = new CLASS ($obj1,$string,\@opts);
44              $obj2  = $obj1->new($string,\@opts)
45
46           In both cases, all arguments are optional.
47
48           Here, CLASS is the class of the new object. For example:
49
50              $date  = new Date::Manip::Date;
51              $delta = new Date::Manip::Delta;
52
53           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
57           For example, if you call either of these:
58
59              $date2 = new Date::Manip::Date $date1;
60              $date2 = $date1->new();
61
62           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
66           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
70              $date = new Date::Manip::Date $delta;
71              $date = new Date::Manip::Date $tz;
72
73           You can even do:
74
75              $date = new Date::Manip::Date $base;
76
77           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
81           There are two special cases. Either of the following will create a
82           new Date::Manip::Base object for handling multiple configurations:
83
84              $base2 = new Date::Manip::Base $base1;
85              $base2 = $base1->new();
86
87           Either of the following will create a new Date::Manip::TZ object
88           with the same Date::Manip::Base object embedded in it:
89
90              $tz2   = new Date::Manip::TZ $tz1;
91              $tz2   = $tz1->new();
92
93           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
97           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
105           In other words, the following are equivalent:
106
107              $date  = new Date::Manip::Date $obj,\@opts;
108
109              $base  = $obj->base();
110              $base2 = $base->new();
111              $date = new Date::Manip::Date $base2;
112              $date->config(@opts);
113
114           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
117              $base2 = new Date::Manip::Base $base1,\@opts;
118              $base2 = $base1->new(\@opts);
119
120           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
126           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
130              $date = new Date::Manip::Date $string,\@opts;
131
132              $date = new Date::Manip::Date;
133              $date->config(@opts);
134              $date->parse($string);
135
136           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
142           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
147           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
152       new_config
153              $obj2 = $obj1->new_config($string,\@opts);
154
155           This creates a new instance with a new Date::Manip::Base object
156           (and possibly a new Date::Manip::TZ object).
157
158           For example,
159
160              $date2 = $date1->new_config();
161
162           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
166           If the object is a Date::Manip::Base object, the following are
167           equivalent:
168
169              $base2 = $base1->new_config();
170
171              $base2 = $base1->new();
172
173           Both $string and \@opts are optional. They are used in the same way
174           they are used in the new method.
175
176       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
182              $date  = $obj->new_date();
183              $date  = new Date::Manip::Date($obj);
184
185              $delta = $obj->new_delta();
186              $delta = new Date::Manip::Date($obj);
187
188           These methods all allow optional ($string,\@opts) arguments.
189

OTHER METHODS

191       base
192       tz
193              $base = $obj->base();
194
195           This returns the Date::Manip::Base object associated with the given
196           object.
197
198           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
201              $tz = $obj->tz();
202
203           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
207       config
208              $obj->config($var1,$val1,$var2,$val2,...);
209
210           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
214       get_config
215              @var = $obj->get_config();
216              $val = $obj->get_config($var1);
217              @val = $obj->get_config($var1,$var2,...);
218
219           This queries the current config values.  With no argument, it will
220           return the list of config variables (all lowercase).
221
222           With one or more arguments, it returns the current values for the
223           config variables passed in (case insensitive).
224
225       err
226              $err = $obj->err();
227
228           This will return the full error message if the previous operation
229           failed for any reason.
230
231              $obj->err(1);
232
233           will clear the error code.
234
235       is_date
236       is_delta
237       is_recur
238              $flag = $obj->is_date();
239
240           Returns 0 or 1, depending on the object. For example, a
241           Date::Manip::Date object returns 1 with the is_date method, and 0
242           for the other two.
243
244       version
245              $vers = $obj->version($flag);
246
247           This returns the version of Date::Manip.
248
249           If $flag is passed in, and $obj is not a Date::Manip::Base object,
250           the version and timezone information will be passed back.
251

KNOWN BUGS

253       None known.
254

BUGS AND QUESTIONS

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

LICENSE

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

AUTHOR

267       Sullivan Beck (sbeck@cpan.org)
268
269
270
271perl v5.16.3                      2014-06-09               Date::Manip::Obj(3)