| Date::Manip::Obj - Base class for Date::Manip objects |
Date::Manip::Obj - Base class for Date::Manip objects
The Date::Manip::Obj class is the base class used for the following Date::Manip classes:
This module is not intended to be called directly and performs no useful function by itself. Instead, use the various derived classes which inherit from it.
This module contains a set of methods used by all Date::Manip classes listed above.
You should be familiar with the the Date::Manip::Objects manpage and the Date::Manip::Config manpage documentation.
In the method descriptions below, the Date::Manip::Date manpage objects will usually be used as examples, but (unless otherwise stated), all of the classes listed above have the same methods, and work in the same fashion.
In the examples below, any $date ($date, $date1, $date2, ...) variable
is a the Date::Manip::Date manpage object. Similarly, $delta, $recur, $tz, and
$base refer to objects in the appropriate class.
Any $obj variable refers to an object in any of the classes.
$obj2 = new CLASS ($obj1,$string,[@parse_opts,]\@opts); $obj2 = $obj1->new($string,[@parse_opts,]\@opts)
In both cases, all arguments are optional.
Here, CLASS is the class of the new object. For example:
$date = new Date::Manip::Date; $delta = new Date::Manip::Delta;
if $obj1 is available, the new object will share as much information
from the old object as possible. The class of the new object may
be derived from the old object as well.
For example, if you call either of these:
$date2 = new Date::Manip::Date $date1; $date2 = $date1->new();
the new date object will use the same embedded the Date::Manip::TZ manpage object. In
the second case, the class of the new object ($date2) is the Date::Manip::Date manpage
because that is the class of the original object.
When specifying CLASS and including an old object, objects do not need to be of the same class. For example, the following are all valid:
$date = new Date::Manip::Date $delta; $date = new Date::Manip::Date $tz;
You can even do:
$date = new Date::Manip::Date $base;
but this will have to create a completely new the Date::Manip::TZ manpage object, which means that optimal performance may not be achieved if a the Date::Manip::TZ manpage object already exists.
There are two special cases. Either of the following will create a new the Date::Manip::Base manpage object for handling multiple configurations:
$base2 = new Date::Manip::Base $base1; $base2 = $base1->new();
Either of the following will create a new the Date::Manip::TZ manpage object with the same the Date::Manip::Base manpage object embedded in it:
$tz2 = new Date::Manip::TZ $tz1; $tz2 = $tz1->new();
The new base object will initially have the same configuration as the original base object, but changing it's configuration will not affect the original base object.
If the \@opts argument is passed in, it is a list reference containing
a list suitable for passing to the config method (described below). In
this case, a new the Date::Manip::Base manpage object (and perhaps the Date::Manip::TZ manpage
object) will be created. The new Base object will start as identical
to the original one (if a previously defined object was used to create
the new object) with the additional options in @opts added.
In other words, the following are equivalent:
$date = new Date::Manip::Date $obj,\@opts;
$base = $obj->base(); $base2 = $base->new(); $date = new Date::Manip::Date $base2; $date->config(@opts);
It should be noted that the options are applied to the NEW object, not the old one. That only matters in one situation:
$base2 = new Date::Manip::Base $base1,\@opts; $base2 = $base1->new(\@opts);
An optional string ($string) may be passed in only when creating
a the Date::Manip::Date manpage, the Date::Manip::Delta manpage, or the Date::Manip::Recur manpage object.
If it is passed in when creating a the Date::Manip::TZ manpage or the Date::Manip::Base manpage
object, a warning will be issued, but execution will continue.
If the string is included, it will be parsed to give an initial value to the object. This will only be done AFTER any options are handled, so the following are equivalent:
$date = new Date::Manip::Date $string,@parse_opts,\@opts;
$date = new Date::Manip::Date; $date->config(@opts); $date->parse($string,@parse_opts);
Once a the Date::Manip::Date manpage object (or any object in any other Date::Manip class) is created, it should always be used to create additional objects in order to preserve cached data for optimal performance and memory usage.
The one caveat is if you are working with multiple configurations as described in the the Date::Manip::Objects manpage document. In that case, you may need to create completely new objects to allow multiple the Date::Manip::Base manpage objects to be used.
$obj2 = $obj1->new_config($string,\@opts);
This creates a new instance with a new the Date::Manip::Base manpage object (and possibly a new the Date::Manip::TZ manpage object).
For example,
$date2 = $date1->new_config();
creates a new the Date::Manip::Date manpage object with a new the Date::Manip::TZ manpage (and the Date::Manip::Base manpage) object. Initially, it is the same configuration as the original object.
If the object is a the Date::Manip::Base manpage object, the following are equivalent:
$base2 = $base1->new_config();
$base2 = $base1->new();
Both $string and \@opts are optional. They are used in the same way they
are used in the new method.
$date = $obj->new_date(); $date = new Date::Manip::Date($obj);
$delta = $obj->new_delta(); $delta = new Date::Manip::Date($obj);
These methods all allow optional ($string,\@opts) arguments.
$base = $obj->base();
This returns the the Date::Manip::Base manpage object associated with the given object.
If $obj is a the Date::Manip::Base manpage object, nothing is returned (i.e. it doesn't
create a new copy of the object).
$tz = $obj->tz();
This returns the the Date::Manip::TZ manpage object associated with the
given object. If $obj is a the Date::Manip::TZ manpage or the Date::Manip::Base manpage object,
nothing is returned.
$obj->config($var1,$val1,$var2,$val2,...);
This will set the value of any configuration variables. Please refer to the the Date::Manip::Config manpage manual for a list of all configuration variables and their description.
@var = $obj->get_config(); $val = $obj->get_config($var1); @val = $obj->get_config($var1,$var2,...);
This queries the current config values. With no argument, it will return the list of config variables (all lowercase).
With one or more arguments, it returns the current values for the config variables passed in (case insensitive).
$err = $obj->err();
This will return the full error message if the previous operation failed for any reason.
$obj->err(1);
will clear the error code.
$flag = $obj->is_date();
Returns 0 or 1, depending on the object. For example, a the Date::Manip::Date manpage object returns 1 with the is_date method, and 0 for the other two.
$vers = $obj->version($flag);
This returns the version of Date::Manip.
If $flag is passed in, and $obj is not a the Date::Manip::Base manpage object, the
version and timezone information will be passed back.
None known.
Please refer to the the Date::Manip::Problems manpage documentation for information on submitting bug reports or questions to the author.
the Date::Manip manpage - main module documentation
This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Sullivan Beck (sbeck@cpan.org)
| Date::Manip::Obj - Base class for Date::Manip objects |