.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Date::Manip::Obj 3"
.TH Date::Manip::Obj 3 "2021-03-01" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Date::Manip::Obj \- Base class for Date::Manip objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The Date::Manip::Obj class is the base class used for the following
Date::Manip classes:
.IP "Date::Manip::Base" 4
.IX Item "Date::Manip::Base"
.PD 0
.IP "Date::Manip::TZ" 4
.IX Item "Date::Manip::TZ"
.IP "Date::Manip::Date" 4
.IX Item "Date::Manip::Date"
.IP "Date::Manip::Delta" 4
.IX Item "Date::Manip::Delta"
.IP "Date::Manip::Recur" 4
.IX Item "Date::Manip::Recur"
.PD
.PP
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.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module contains a set of methods used by all Date::Manip classes
listed above.
.PP
You should be familiar with the Date::Manip::Objects and
Date::Manip::Config documentation.
.PP
In the method descriptions below, Date::Manip::Date 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.
.SH "METHODS FOR CREATING OBJECTS"
.IX Header "METHODS FOR CREATING OBJECTS"
In the examples below, any variable named some variation of \f(CW$date\fR (\f(CW$date\fR,
\&\f(CW$date1\fR, \f(CW$date2\fR, ...) is a Date::Manip::Date object. Similarly, \f(CW$delta\fR,
\&\f(CW$recur\fR, \f(CW$tz\fR, and \f(CW$base\fR refer to objects in the appropriate class.
.PP
Any \f(CW$obj\fR variable refers to an object in any of the classes.
.IP "\fBnew\fR" 4
.IX Item "new"
There are two ways to use the new method. They are:
.Sp
.Vb 2
\&   $obj2  = new CLASS ($obj1,$string,@parse_opts,\e@opts);
\&   $obj2  = $obj1\->new($string,@parse_opts,\e@opts)
.Ve
.Sp
In both cases, all arguments are optional.
.Sp
Both methods are used to create a new object of a given class.  In the
first case, \fB\s-1CLASS\s0\fR is the class of the new object. For example:
.Sp
.Vb 2
\&   $date  = new Date::Manip::Date;
\&   $delta = new Date::Manip::Delta;
.Ve
.Sp
In the second method, the class of the new object will be derived from
the first object.  For example:
.Sp
.Vb 2
\&   $date1 = new Date::Manip::Date;
\&   $date2 = $date1\->new();
.Ve
.Sp
the class of the second object (\f(CW$date2\fR) is Date::Manip::Date
because that is the class of the object (\f(CW$date1\fR) used to create it.
.Sp
In both first method (when a \f(CW$obj1\fR is passed in) and always in the
second method, the new object will share as much information from the
old object (\f(CW$obj1\fR) as possible.
.Sp
For example, if you call either of these:
.Sp
.Vb 2
\&   $date2 = new Date::Manip::Date $date1;
\&   $date2 = $date1\->new();
.Ve
.Sp
the new date object will use the same embedded Date::Manip::TZ and
Date::Manip::Base objects.
.Sp
When specifying \s-1CLASS\s0 and including an old object, objects do not need to
be of the same class.  For example, the following are all valid:
.Sp
.Vb 2
\&   $date = new Date::Manip::Date $delta;
\&   $date = new Date::Manip::Date $tz;
.Ve
.Sp
You can even do:
.Sp
.Vb 1
\&   $date = new Date::Manip::Date $base;
.Ve
.Sp
but this will have to create a completely new Date::Manip::TZ object,
which means that optimal performance may not be achieved if a
Date::Manip::TZ object already exists.
.Sp
There are two special cases. Either of the following will create
a new Date::Manip::Base object for handling multiple configurations:
.Sp
.Vb 2
\&   $base2 = new Date::Manip::Base $base1;
\&   $base2 = $base1\->new();
.Ve
.Sp
Either of the following will create a new Date::Manip::TZ object with
the same Date::Manip::Base object embedded in it:
.Sp
.Vb 2
\&   $tz2   = new Date::Manip::TZ $tz1;
\&   $tz2   = $tz1\->new();
.Ve
.Sp
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.
.Sp
If the \f(CW\*(C`\e@opts\*(C'\fR argument is passed in, it is a list reference containing
a list suitable for passing to the \fBconfig\fR method (described below). In
this case, a new Date::Manip::Base object (and perhaps Date::Manip::TZ
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 \f(CW@opts\fR added.
.Sp
In other words, the following are equivalent:
.Sp
.Vb 1
\&   $date  = new Date::Manip::Date $obj,\e@opts;
\&
\&   $base  = $obj\->base();
\&   $base2 = $base\->new();
\&   $date = new Date::Manip::Date $base2;
\&   $date\->config(@opts);
.Ve
.Sp
It should be noted that the options are applied to the \s-1NEW\s0 Date::Manip::Base
object, not the old one.
.Sp
An optional string (\f(CW$string\fR and parse opts \f(CW@parse_opts\fR) may be
passed in only when creating a Date::Manip::Date,
Date::Manip::Delta, or Date::Manip::Recur object.  If passed in
when creating a Date::Manip::TZ or Date::Manip::Base object, a
warning will be issued, but execution will continue.
.Sp
If the string is included, it will be parsed to give an initial value
to the object. This will only be done \s-1AFTER\s0 any options are handled,
so the following are equivalent:
.Sp
.Vb 1
\&   $date = new Date::Manip::Date $string,@parse_opts,\e@opts;
\&
\&   $date = new Date::Manip::Date;
\&   $date\->config(@opts);
\&   $date\->parse($string,@parse_opts);
.Ve
.Sp
Once a Date::Manip::Date 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.
.Sp
The one caveat is if you are working with multiple configurations
as described in the Date::Manip::Objects document. In that case,
you may need to create completely new objects to allow multiple
Date::Manip::Base objects to be used.
.IP "\fBnew_config\fR" 4
.IX Item "new_config"
.Vb 1
\&   $obj2 = $obj1\->new_config($string,\e@opts);
.Ve
.Sp
This creates a new instance with a new Date::Manip::Base object (and possibly
a new Date::Manip::TZ object).
.Sp
For example,
.Sp
.Vb 1
\&   $date2 = $date1\->new_config();
.Ve
.Sp
creates a new Date::Manip::Date object with a new Date::Manip::TZ (and
Date::Manip::Base) object. Initially, it is the same configuration as
the original object.
.Sp
If the object is a Date::Manip::Base object, the following are equivalent:
.Sp
.Vb 1
\&   $base2 = $base1\->new_config();
\&
\&   $base2 = $base1\->new();
.Ve
.Sp
Both \f(CW$string\fR and \f(CW\*(C`\e@opts\*(C'\fR are optional. They are used in the same way they
are used in the new method.
.IP "\fBnew_date\fR" 4
.IX Item "new_date"
.PD 0
.IP "\fBnew_delta\fR" 4
.IX Item "new_delta"
.IP "\fBnew_recur\fR" 4
.IX Item "new_recur"
.PD
These are shortcuts for specifying the class. The following sets of
calls are all equivalent:
.Sp
.Vb 2
\&   $date  = $obj\->new_date();
\&   $date  = new Date::Manip::Date($obj);
\&
\&   $delta = $obj\->new_delta();
\&   $delta = new Date::Manip::Date($obj);
.Ve
.Sp
These methods all allow optional \f(CW\*(C`($string,\e@opts)\*(C'\fR arguments.
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.IP "\fBbase\fR" 4
.IX Item "base"
.PD 0
.IP "\fBtz\fR" 4
.IX Item "tz"
.PD
.Vb 1
\&   $base = $obj\->base();
.Ve
.Sp
This returns the Date::Manip::Base object associated with the
given object.
.Sp
If \f(CW$obj\fR is a Date::Manip::Base object, nothing is returned (i.e. it doesn't
create a new copy of the object).
.Sp
.Vb 1
\&   $tz = $obj\->tz();
.Ve
.Sp
This returns the Date::Manip::TZ object associated with the
given object. If \f(CW$obj\fR is a Date::Manip::TZ or Date::Manip::Base object,
nothing is returned.
.IP "\fBconfig\fR" 4
.IX Item "config"
.Vb 1
\&   $obj\->config($var1,$val1,$var2,$val2,...);
.Ve
.Sp
This will set the value of any configuration variables. Please refer to the
Date::Manip::Config manual for a list of all configuration variables and their
description.
.IP "\fBget_config\fR" 4
.IX Item "get_config"
.Vb 3
\&   @var = $obj\->get_config();
\&   $val = $obj\->get_config($var1);
\&   @val = $obj\->get_config($var1,$var2,...);
.Ve
.Sp
This queries the current config values.  With no argument, it will return
the list of config variables (all lowercase).
.Sp
With one or more arguments, it returns the current values for the config
variables passed in (case insensitive).
.IP "\fBerr\fR" 4
.IX Item "err"
.Vb 1
\&   $err = $obj\->err();
.Ve
.Sp
This will return the full error message if the previous operation failed
for any reason.
.Sp
.Vb 1
\&   $obj\->err(1);
.Ve
.Sp
will clear the error code.
.IP "\fBis_date\fR" 4
.IX Item "is_date"
.PD 0
.IP "\fBis_delta\fR" 4
.IX Item "is_delta"
.IP "\fBis_recur\fR" 4
.IX Item "is_recur"
.PD
.Vb 1
\&   $flag = $obj\->is_date();
.Ve
.Sp
Returns 0 or 1, depending on the object. For example, a Date::Manip::Date
object returns 1 with the is_date method, and 0 for the other two.
.IP "\fBversion\fR" 4
.IX Item "version"
.Vb 1
\&   $vers = $obj\->version($flag);
.Ve
.Sp
This returns the version of Date::Manip.
.Sp
If \f(CW$flag\fR is passed in, and \f(CW$obj\fR is not a Date::Manip::Base object, the
version and timezone information will be passed back.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
None known.
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Manip        \- main module documentation
.SH "LICENSE"
.IX Header "LICENSE"
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)