.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::Date 3pm"
.TH Class::Date 3pm "2014-05-03" "perl v5.20.0" "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"
Class::Date \- Class for easy date and time manipulation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Class::Date qw(:errors date localdate gmdate now \-DateParse \-EnvC);
\&  
\&  # creating absolute date object (local time)
\&  $date = Class::Date\->new( [$year,$month,$day,$hour,$min,$sec]);
\&  $date = date [$year,$month,$day,$hour,$min,$sec]; 
\&    # ^\- "date" is an exportable function, the same as Class::Date\->new
\&  $date = date { year => $year, month => $month, day => $day,
\&    hour => $hour, min => $min, sec => $sec };
\&  $date = date "2001\-11\-12 07:13:12";
\&  $date = localdate "2001\-12\-11";
\&  $date = now;                      #  the same as date(time)
\&  $date = date($other_date_object); # cloning
\&  ...
\&
\&  # creating absolute date object (GMT)
\&  $date = Class::Date\->new( [$year,$month,$day,$hour,$min,$sec],\*(AqGMT\*(Aq);
\&  $date = gmdate "2001\-11\-12 17:13";
\&  ...
\&
\&  # creating absolute date object in any other timezone
\&  $date = Class::Date\->new( [$year,$month,$day,$hour,$min,$sec],\*(AqIceland\*(Aq );
\&  $date = date "2001\-11\-12 17:13", \*(AqIceland\*(Aq;
\&  $date2 = $date\->new([$y2, $m2, $d2, $h2, $m2, $s2]); 
\&    # ^\- timezone is inherited from the $date object
\&
\&  # creating relative date object
\&  # (normally you don\*(Aqt need to create this object explicitly)
\&  $reldate = Class::Date::Rel\->new( "3Y 1M 3D 6h 2m 4s" );
\&  $reldate = Class::Date::Rel\->new( "6Y" );
\&  $reldate = Class::Date::Rel\->new( $secs );  # secs
\&  $reldate = Class::Date::Rel\->new( [$year,$month,$day,$hour,$min,$sec] );
\&  $reldate = Class::Date::Rel\->new( { year => $year, month => $month, day => $day,
\&    hour => $hour, min => $min, sec => $sec } );
\&  $reldate = Class::Date::Rel\->new( "2001\-11\-12 07:13:12" );
\&  $reldate = Class::Date::Rel\->new( "2001\-12\-11" );
\&
\&  # getting values of an absolute date object
\&  $date;              # prints the date in default output format (see below)
\&  $date\->year;        # year, e.g: 2001
\&  $date\->_year;       # year \- 1900, e.g. 101
\&  $date\->yr;          # 2\-digit year 0\-99, e.g 1
\&  $date\->mon;         # month 1..12
\&  $date\->month;       # same as prev.
\&  $date\->_mon;        # month 0..11
\&  $date\->_month;      # same as prev.
\&  $date\->day;         # day of month
\&  $date\->mday;        # day of month
\&  $date\->day_of_month;# same as prev.
\&  $date\->hour;
\&  $date\->min;
\&  $date\->minute;      # same as prev.
\&  $date\->sec;
\&  $date\->second;      # same as prev.
\&  $date\->wday;        # 1 = Sunday
\&  $date\->_wday;       # 0 = Sunday
\&  $date\->day_of_week; # same as prev.
\&  $date\->yday;        
\&  $date\->day_of_year; # same as prev.
\&  $date\->isdst;       # DST?
\&  $date\->daylight_savings; # same as prev.
\&  $date\->epoch;       # UNIX time_t
\&  $date\->monname;     # name of month, eg: March
\&  $date\->monthname;   # same as prev.
\&  $date\->wdayname;    # Thursday
\&  $date\->day_of_weekname # same as prev.
\&  $date\->hms          # 01:23:45
\&  $date\->ymd          # 2000/02/29
\&  $date\->mdy          # 02/29/2000
\&  $date\->dmy          # 29/02/2000
\&  $date\->meridiam     # 01:23 AM
\&  $date\->ampm         # AM/PM
\&  $date\->string       # 2000\-02\-29 12:21:11 (format can be changed, look below)
\&  "$date"             # same as prev.
\&  $date\->tzoffset     # timezone\-offset
\&  $date\->strftime($format) # POSIX strftime (without the huge POSIX.pm)
\&  $date\->tz           # returns the base timezone as you specify, eg: CET
\&  $date\->tzdst        # returns the real timezone with dst information, eg: CEST
\&
\&  ($year,$month,$day,$hour,$min,$sec)=$date\->array;
\&  ($year,$month,$day,$hour,$min,$sec)=@{ $date\->aref };
\&  # !! $year: 1900\-, $month: 1\-12
\&
\&  ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=$date\->struct;
\&  ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=@{ $date\->sref };
\&  # !! $year: 0\-, $month: 0\-11
\&
\&  $hash=$date\->href; # $href can be reused as a constructor
\&  print $hash\->{year}."\-".$hash\->{month}. ... $hash\->{sec} ... ;
\&  
\&  %hash=$date\->hash;
\&  # !! $hash{year}: 1900\-, $hash{month}: 1\-12
\&
\&  $date\->month_begin  # First day of the month (date object)
\&  $date\->month_end    # Last day of the month
\&  $date\->days_in_month # 28..31
\&
\&  # constructing new date based on an existing one:
\&  $new_date = $date\->clone;
\&  $new_date = $date\->clone( year => 1977, sec => 14 );
\&  # valid keys: year, _year, month, mon, _month, _mon, day, mday, day_of_month,
\&  #             hour, min, minute, sec, second, tz
\&  # constructing a new date, which is the same as the original, but in 
\&  # another timezone:
\&  $new_date = $date\->to_tz(\*(AqIceland\*(Aq);
\&
\&  # changing date format
\&  {
\&    local $Class::Date::DATE_FORMAT="%Y%m%d%H%M%S";
\&    print $date       # result: 20011222000000
\&    $Class::Date::DATE_FORMAT=undef;
\&    print $date       # result: Thu Oct 13 04:54:34 1994
\&    $Class::Date::DATE_FORMAT="%Y/%m/%d"
\&    print $date       # result: 1994/10/13
\&  }
\&
\&  # error handling
\&  $a = date($date_string);
\&  if ($a) { # valid date
\&    ...
\&  } else { # invalid date
\&    if ($a\->error == E_INVALID) { ... }
\&    print $a\->errstr;
\&  }
\&
\&  # adjusting DST in calculations  (see the doc)
\&  $Class::Date::DST_ADJUST = 1; # this is the default
\&  $Class::Date::DST_ADJUST = 0;
\&
\&  # "month\-border adjust" flag 
\&  $Class::Date::MONTH_BORDER_ADJUST = 0; # this is the default
\&  print date("2001\-01\-31")+\*(Aq1M\*(Aq; # will print 2001\-03\-03
\&  $Class::Date::MONTH_BORDER_ADJUST = 1;
\&  print date("2001\-01\-31")+\*(Aq1M\*(Aq; # will print 2001\-02\-28
\&
\&  # date range check
\&  $Class::Date::RANGE_CHECK = 0; # this is the default
\&  print date("2001\-02\-31"); # will print 2001\-03\-03
\&  $Class::Date::RANGE_CHECK = 1;
\&  print date("2001\-02\-31"); # will print nothing
\&
\&  # getting values of a relative date object
\&  $reldate;              # reldate in seconds (assumed 1 month = 2_629_744 secs)
\&  $reldate\->year;
\&  $reldate\->mon;
\&  $reldate\->month;       # same as prev.
\&  $reldate\->day;
\&  $reldate\->hour;
\&  $reldate\->min;
\&  $reldate\->minute;      # same as prev.
\&  $reldate\->sec;         # same as $reldate
\&  $reldate\->second;      # same as prev.
\&  $reldate\->sec_part;    # "second" part of the relative date
\&  $reldate\->mon_part;    # "month"  part of the relative date
\&
\&  # arithmetic with dates:
\&  print date([2001,12,11,4,5,6])\->truncate; 
\&                               # will print "2001\-12\-11"
\&  $new_date = $date+$reldate;
\&  $date2    = $date+\*(Aq3Y 2D\*(Aq;   # 3 Years and 2 days
\&  $date3    = $date+[1,2,3];   # $date plus 1 year, 2 months, 3 days
\&  $date4    = $date+\*(Aq3\-1\-5\*(Aq    # $date plus 3 years, 1 months, 5 days
\&
\&  $new_date = $date\-$reldate;
\&  $date2    = $date\-\*(Aq3Y\*(Aq;      # 3 Yearss
\&  $date3    = $date\-[1,2,3];   # $date minus 1 year, 2 months, 3 days
\&  $date4    = $date\-\*(Aq3\-1\-5\*(Aq    # $date minus 3 years, 1 month, 5 days
\&
\&  $new_reldate = $date1\-$date2;
\&  $reldate2 = Class::Date\->new(\*(Aq2000\-11\-12\*(Aq)\-\*(Aq2000\-11\-10\*(Aq;
\&  $reldate3    = $date3\-\*(Aq1977\-11\-10\*(Aq;
\&
\&  $days_between = (Class::Date\->new(\*(Aq2001\-11\-12\*(Aq)\-\*(Aq2001\-07\-04\*(Aq)\->day;
\&
\&  # comparison between absolute dates
\&  print $date1 > $date2 ? "I am older" : "I am younger";
\&
\&  # comparison between relative dates
\&  print $reldate1 > $reldate2 ? "I am faster" : "I am slower";
\&
\&  # Adding / Subtracting months and years are sometimes tricky:
\&  print date("2001\-01\-29") + \*(Aq1M\*(Aq \- \*(Aq1M\*(Aq; # gives "2001\-02\-01"
\&  print date("2000\-02\-29") + \*(Aq1Y\*(Aq \- \*(Aq1Y\*(Aq; # gives "2000\-03\-01"
\&
\&  # Named interface ($date2 does not necessary to be a Class::Date object)
\&  $date1\->string;               # same as $date1 in scalar context
\&  $date1\->subtract($date2);     # same as $date1 \- $date2
\&  $date1\->add($date2);          # same as $date1 + $date2
\&  $date1\->compare($date2);      # same as $date1 <=> $date2
\&
\&  $reldate1\->sec;               # same as $reldate1 in numeric or scalar context
\&  $reldate1\->compare($reldate2);# same as $reldate1 <=> $reldate2
\&  $reldate1\->add($reldate2);    # same as $reldate1 + $reldate2
\&  $reldate1\->neg                # used for subtraction
\&
\&  # Disabling Class::Date warnings at load time
\&  BEGIN { $Class::Date::WARNINGS=0; }
\&  use Class::Date;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is intended to provide a general-purpose date and datetime type
for perl. You have a Class::Date class for absolute date and datetime, and have 
a Class::Date::Rel class for relative dates.
.PP
You can use \*(L"+\*(R", \*(L"\-\*(R", \*(L"<\*(R" and \*(L">\*(R" operators as with native perl data types.
.SH "USAGE"
.IX Header "USAGE"
If you want to use a date object, you need to do the following:
.PP
.Vb 3
\&  \- create a new object
\&  \- do some operations (+, \-, comparison)
\&  \- get result back
.Ve
.SS "Creating a new date object"
.IX Subsection "Creating a new date object"
You can create a date object by the \*(L"date\*(R", \*(L"localdate\*(R" or \*(L"gmdate\*(R" function, 
or by calling the Class::Date constructor.
.PP
\&\*(L"date\*(R" and \*(L"Class::Date\->new\*(R" are equivalent, both has two arguments: The
date and the timezone.
.PP
.Vb 3
\&  $date1= date [2000,11,12];
\&  $date2= Class::Date\->new([2000,06,11,13,11,22],\*(AqGMT\*(Aq);
\&  $date2= $date1\->new([2000,06,11,13,11,22]);
.Ve
.PP
If the timezone information is omitted, then it first check if \*(L"new\*(R" is 
called as an object method or a class method. If it is an object method,
then it inherits the timezone from the base object, otherwise the default
timezone is used ($Class::Date::DEFAULT_TIMEZONE), which is usually set to
the local timezone (which is stored in \f(CW$Class::Date::LOCAL_TIMEZONE\fR). These
two variables are set only once to the value, which is returned by the
\&\fIClass::Date::local_timezone()\fR function. You can change these values
whenever you want.
.PP
\&\*(L"localdate \f(CW$x\fR\*(R" is equivalent to \*(L"date \f(CW$x\fR, \f(CW$Class::Date::LOCAL_TIMEZONE\fR\*(R", 
\&\*(L"gmdate \f(CW$x\fR\*(R" is equivalent to \*(L"date \f(CW$x\fR, \f(CW$Class::Date::GMT_TIMEZONE\fR\*(R".
.PP
\&\f(CW$Class::Date::GMT_TIMEZONE\fR is set to '\s-1GMT\s0' by default.
.PP
.Vb 2
\&  $date1= localdate [2000,11,12];
\&  $date2= gmdate [2000,4,2,3,33,33];
\&
\&  $date = localdate(time);
.Ve
.PP
The format of the accepted input date can be:
.IP "[$year,$month,$day,$hour,$min,$sec]" 4
.IX Item "[$year,$month,$day,$hour,$min,$sec]"
An array reference with 6 elements. The missing elements have default
values (year: 2000, month, day: 1, hour, min, sec: 0)
.ie n .IP "{ year => $year, month => $month, day => $day, hour => $hour, min => $min, sec => $sec }" 4
.el .IP "{ year => \f(CW$year\fR, month => \f(CW$month\fR, day => \f(CW$day\fR, hour => \f(CW$hour\fR, min => \f(CW$min\fR, sec => \f(CW$sec\fR }" 4
.IX Item "{ year => $year, month => $month, day => $day, hour => $hour, min => $min, sec => $sec }"
A hash reference with the same 6 elements as above.
.ie n .IP """YYYYMMDDhhmmss""" 4
.el .IP "``YYYYMMDDhhmmss''" 4
.IX Item "YYYYMMDDhhmmss"
A mysql-style timestamp value, which consist of at least 14 digit.
.ie n .IP """973897262""" 4
.el .IP "``973897262''" 4
.IX Item "973897262"
A valid 32\-bit integer: This is parsed as a unix time.
.ie n .IP """YYYY-MM-DD hh:mm:ss""" 4
.el .IP "``YYYY-MM-DD hh:mm:ss''" 4
.IX Item "YYYY-MM-DD hh:mm:ss"
A standard \s-1ISO\s0(\-like) date format. Additional \*(L".fraction\*(R" part is ignored, 
\&\*(L":ss\*(R" can be omitted.
.IP "additional input formats" 4
.IX Item "additional input formats"
You can specify \*(L"\-DateParse\*(R" as  an import parameter, e.g:
.Sp
.Vb 1
\&  use Class::Date qw(date \-DateParse);
.Ve
.Sp
With this, the module will try to load Date::Parse module, and if it find it then all 
these formats can be used as an input. Please refer to the Date::Parse
documentation.
.SS "Operations"
.IX Subsection "Operations"
.IP "addition" 4
.IX Item "addition"
You can add the following to a Class::Date object:
.Sp
.Vb 2
\&  \- a valid Class::Date::Rel object
\&  \- anything, that can be used for creating a new Class::Date::Rel object
.Ve
.Sp
It means that you don't need to create a new Class::Date::Rel object every
time when you add something to the Class::Date object, it creates them
automatically:
.Sp
.Vb 1
\&  $date= Class::Date\->new(\*(Aq2001\-12\-11\*(Aq)+Class::Date::Rel\->new(\*(Aq3Y\*(Aq);
.Ve
.Sp
is the same as:
.Sp
.Vb 1
\&  $date= date(\*(Aq2001\-12\-11\*(Aq)+\*(Aq3Y\*(Aq;
.Ve
.Sp
You can provide a Class::Date::Rel object in the following form:
.RS 4
.IP "array ref" 4
.IX Item "array ref"
The same format as seen in Class::Date format, except the default values are
different: all zero.
.IP "hash ref" 4
.IX Item "hash ref"
The same format as seen in Class::Date format, except the default values are
different: all zero.
.ie n .IP """973897262""" 4
.el .IP "``973897262''" 4
.IX Item "973897262"
A valid 32\-bit integer is parsed as seconds.
.ie n .IP """YYYY-MM-DD hh:mm:ss""" 4
.el .IP "``YYYY-MM-DD hh:mm:ss''" 4
.IX Item "YYYY-MM-DD hh:mm:ss"
A standard \s-1ISO\s0 date format, but this is parsed as relative date date and time,
so month, day and year can be zero (and defaults to zero).
.ie n .IP """12Y 6M 6D 20h 12m 5s""" 4
.el .IP "``12Y 6M 6D 20h 12m 5s''" 4
.IX Item "12Y 6M 6D 20h 12m 5s"
This special string can be used if you don't want to use the \s-1ISO\s0 format. This
string consists of whitespace separated tags, each tag consists of a number and
a unit. The units can be:
.Sp
.Vb 6
\&  Y: year
\&  M: month
\&  D: day
\&  h: hour
\&  m: min
\&  s: sec
.Ve
.Sp
The number and unit must be written with no space between them.
.RE
.RS 4
.RE
.IP "substraction" 4
.IX Item "substraction"
The same rules are true for substraction, except you can substract 
two Class::Date object from each other, and you will get a Class::Date::Rel
object:
.Sp
.Vb 2
\&  $reldate=$date1\-$date2;
\&  $reldate=date(\*(Aq2001\-11\-12 12:11:07\*(Aq)\-date(\*(Aq2001\-10\-07 10:3:21\*(Aq);
.Ve
.Sp
In this case, the \*(L"month\*(R" field of the \f(CW$reldate\fR object will be 0,
and the other fields will contain the difference between two dates;
.IP "comparison" 4
.IX Item "comparison"
You can compare two Class::Date objects, or one Class::Date object and
another data, which can be used for creating a new Class::Data object.
.Sp
It means that you don't need to bless both objects, one of them can be a
simple string, array ref, hash ref, etc (see how to create a date object).
.Sp
.Vb 1
\&  if ( date(\*(Aq2001\-11\-12\*(Aq) > date(\*(Aq2000\-11\-11\*(Aq) ) { ... }
.Ve
.Sp
or
.Sp
.Vb 1
\&  if ( date(\*(Aq2001\-11\-12\*(Aq) > \*(Aq2000\-11\-11\*(Aq ) { ... }
.Ve
.IP "truncate" 4
.IX Item "truncate"
You can chop the time value from this object (set hour, min and sec to 0)
with the \*(L"truncate\*(R" or \*(L"trunc\*(R" method. It does not modify the specified
object, it returns with a new one.
.IP "clone" 4
.IX Item "clone"
You can create new date object based on an existing one, by using the \*(L"clone\*(R"
method. Note, this \s-1DOES NOT\s0 modify the base object.
.Sp
.Vb 1
\&  $new_date = $date\->clone( year => 2001, hour => 14 );
.Ve
.Sp
The valid keys are: year, _year, month, mon, _month, _mon, day, mday, 
day_of_month, hour, min, minute, sec, second, tz.
.Sp
There is a \*(L"set\*(R" method, which does the same as the \*(L"clone\*(R", it exists 
only for compatibility.
.IP "to_tz" 4
.IX Item "to_tz"
You can use \*(L"to_tz\*(R" to create a new object, which means the same time as
the base object, but in the different timezone.
.Sp
Note that \f(CW$date\fR\->clone( tz => 'Iceland') and \f(CW$date\fR\->to_tz('Iceland') is not
the same! Cloning a new object with setting timezone will preserve the
time information (hour, minute, second, etc.), but transfer the time into
other timezone, while to_tz usually change these values based on the
difference between the source and the destination timezone.
.IP "Operations with Class::Date::Rel" 4
.IX Item "Operations with Class::Date::Rel"
The Class::Date::Rel object consists of a month part and a day part. Most
people only use the \*(L"day\*(R" part of it. If you use both part, then you can get
these parts with the \*(L"sec_part\*(R" and \*(L"mon_part\*(R" method. If you use \*(L"sec\*(R",
\&\*(L"month\*(R", etc. methods or if you use this object in a mathematical conent,
then this object is converted to one number, which is interpreted as second.
The conversion is based on a 30.436 days month. Don't use it too often,
because it is confusing...
.Sp
If you use Class::Date::Rel in an expression with other Class::Date or
Class::Date::Rel objects, then it does what is expected:
.Sp
.Vb 1
\&  date(\*(Aq2001\-11\-12\*(Aq)+\*(Aq1M\*(Aq will be \*(Aq2001\-12\-12\*(Aq
.Ve
.Sp
and
.Sp
.Vb 1
\&  date(\*(Aq1996\-02\-11\*(Aq)+\*(Aq2M\*(Aq will be \*(Aq1996\-04\-11\*(Aq
.Ve
.SS "Accessing data from a Class::Date and Class::Date::Rel object"
.IX Subsection "Accessing data from a Class::Date and Class::Date::Rel object"
You can use the methods methods described at the top of the document 
if you want to access parts of the data
which is stored in a Class::Date and Class::Date::Rel object.
.SS "Error handling"
.IX Subsection "Error handling"
If a date object became invalid, then the object will be reblessed to
Class::Date::Invalid. This object is false in boolean environment, so you can
test the date validity like this:
.PP
.Vb 7
\&  $a = date($input_date);
\&  if ($a) { # valid date
\&      ...
\&  } else { # invalid date
\&      if ($a\->error == E_INVALID) { ... }
\&      print $a\->errstr;
\&  }
.Ve
.PP
Note even the date is invalid, the expression \*(L"defined \f(CW$a\fR\*(R" always returns
true, so the following is wrong:
.PP
.Vb 2
\&  $a = date($input_date);
\&  if (defined $a) ... # WRONG!!!!
.Ve
.PP
You can test the error by getting the \f(CW$date\fR\->error value. You might import
the \*(L":errors\*(R" tag:
.PP
.Vb 1
\&  use Class::Date qw(:errors);
.Ve
.PP
Possible error values are:
.IP "E_OK" 4
.IX Item "E_OK"
No errors.
.IP "E_INVALID" 4
.IX Item "E_INVALID"
Invalid date. It is set when some of the parts of the date are invalid, and
Time::Local functions cannot convert them to a valid date.
.IP "E_RANGE" 4
.IX Item "E_RANGE"
This error is set, when parts of the date are valid, but the whole date is
not valid, e.g. 2001\-02\-31. When the \f(CW$Class::Date::RANGE_CHECK\fR is not set, then
these date values are automatically converted to a valid date: 2001\-03\-03,
but the \f(CW$date\fR\->error value are set to E_RANGE. If \f(CW$Class::Date::RANGE_CHECK\fR
is set, then a date \*(L"2001\-02\-31\*(R" became invalid date.
.IP "E_UNPARSABLE" 4
.IX Item "E_UNPARSABLE"
This error is set, when the constructor cannot be created from a scalar, e.g:
.Sp
.Vb 1
\&  $a = date("4kd sdlsdf lwekrmk");
.Ve
.IP "E_UNDEFINED" 4
.IX Item "E_UNDEFINED"
This error is set, when you want to create a date object from an undefined
value:
.Sp
.Vb 1
\&  $a = Class::Date\->new(undef);
.Ve
.Sp
Note, that localdate(undef) will create a valid object, because it calls
\&\f(CW$Class::Dat\fRe(time).
.PP
You can get the error in string form by calling the \*(L"errstr\*(R" method.
.SH "DST_ADJUST"
.IX Header "DST_ADJUST"
\&\f(CW$DST_ADJUST\fR is an important configuration option.
.PP
If it is set to true (default), then the module adjusts the date and time
when the operation switches the border of \s-1DST.\s0 With this setting, you are
ignoring the effect of \s-1DST.\s0
.PP
When \f(CW$DST_ADJUST\fR is set to false, then no adjustment is done, the
calculation will be based on the exact time difference.
.PP
You will see the difference through an example:
.PP
.Vb 1
\&  $Class::Date::DST_ADJUST=1;
\&
\&  print date("2000\-10\-29", "CET") + "1D";
\&  # This will print 2000\-10\-30 00:00:00
\&
\&  print date("2001\-03\-24 23:00:00", "CET") + "1D";
\&  # This will be 2001\-03\-25 23:00:00
\&
\&  print date("2001\-03\-25", "CET") + "1D";
\&  # This will be 2001\-03\-26 00:00:00
\&
\&
\&  $Class::Date::DST_ADJUST=0;
\&
\&  print date("2000\-10\-29", "CET") + "1D";
\&  # This will print 2000\-10\-29 23:00:00
\&
\&  print date("2001\-03\-24 23:00:00", "CET") + "1D";
\&  # This will be 2001\-03\-26 00:00:00
.Ve
.SH "MONTHS AND YEARS"
.IX Header "MONTHS AND YEARS"
If you add or subtract \*(L"months\*(R" and \*(L"years\*(R" to a date, you may get wrong 
dates, e.g when you add one month to 2001\-01\-31, you expect to get
2001\-02\-31, but this date is invalid and converted to 2001\-03\-03. Thats' why
.PP
.Vb 1
\&  date("2001\-01\-31") + \*(Aq1M\*(Aq \- \*(Aq1M\*(Aq != "2001\-01\-31"
.Ve
.PP
This problem can occur only with months and years, because others can 
easily be converted to seconds.
.SH "MONTH_BORDER_ADJUST"
.IX Header "MONTH_BORDER_ADJUST"
\&\f(CW$MONTH_BORDER_ADJUST\fR variable is used to switch on or off the 
month-adjust feature. This is used only when someone adds months or years to
a date and then the resulted date became invalid. An example: adding one
month to \*(L"2001\-01\-31\*(R" will result \*(L"2001\-02\-31\*(R", and this is an invalid date.
.PP
When \f(CW$MONTH_BORDER_ADJUST\fR is false, this result simply normalized, and
becomes \*(L"2001\-03\-03\*(R". This is the default behaviour.
.PP
When \f(CW$MONTH_BORDER_ADJUST\fR is true, this result becomes \*(L"2001\-02\-28\*(R". So when
the date overflows, then it returns the last day insted.
.PP
Both settings keep the time information.
.SH "WORKING WITHOUT A C COMPILER"
.IX Header "WORKING WITHOUT A C COMPILER"
Class::Date can be used without a C compiler since 1.0.8. If you want to do 
this, you only need to copy the \*(L"Date.pm\*(R" whereever your perl compiler searches
for it. You must make a \*(L"Class\*(R" directory for it before.
.PP
In Debian GNU/Linux system (woody) , a good choice can be the following:
.PP
.Vb 2
\&  mkdir /usr/local/share/perl/5.6.1/Class
\&  cp Date.pm /usr/local/share/perl/5.6.1/Class
.Ve
.PP
And the module will work.
.PP
You can use the \f(CW$WARNINGS\fR switch to switch off the complains about the missing
\&\s-1XS\s0 part from your perl program:
.PP
.Vb 3
\&    BEGIN { $Class::Date::WARNINGS=0; }
\&    use Class::Date;
\&    ...
.Ve
.SH "TIMEZONE SUPPORT"
.IX Header "TIMEZONE SUPPORT"
Since 1.0.11, Class::Date handle timezones natively on most platforms (see
the \s-1BUGS AND LIMITATIONS\s0 section for more info).
.PP
When the module is loaded, then it determines the local base timezone by
calling the \fIClass::Date::local_timezone()\fR function, and stores these values
into two variables, these are: \f(CW$Class::Date::LOCAL_TIMEZONE\fR and
\&\f(CW$Class::Date::DEFAULT_TIMEZONE\fR. The first value is used, when you call the
\&\*(L"localdate\*(R" function, the second value is used, when you call the \*(L"date\*(R"
function and you don't specify the timezone. There is
a \f(CW$Class::Date::GMT_TIMEZONE\fR function also, which is used by the \*(L"gmdate\*(R"
function, this is set to '\s-1GMT\s0'.
.PP
You can query the timezone of a date object by calling the \f(CW$date\fR\->tz
method. Note this value returns the timezone as you specify, so if you
create the object with an unknown timezone, you will get this back. If you
want to query the effective timezone, you can call the \f(CW$date\fR\->tzdst method.
This method returns only valid timezones, but it is not necessarily the
timezone, which can be used to create a new object. For example
\&\f(CW$date\fR\->tzdst can return '\s-1CEST\s0', which is not a valid base timezone, because
it contains daylight savings information also. On Linux systems, you can
see the possible base timezones in the /usr/share/zoneinfo directory.
.PP
In Class::Date 1.1.6, a new environment variable is introduced:
\&\f(CW$Class::Date::NOTZ_TIMEZONE\fR. This variable stores the local timezone, which
is used, when the \s-1TZ\s0 environment variable is not set. It is introduced,
because there are some systems, which cannot handle the queried timezone
well. For example the local timezone is \s-1CST,\s0 it is returned by the \fItzname()\fR
perl function, but when I set the \s-1TZ\s0 environment variable to \s-1CST,\s0 it
works like it would be \s-1GMT. \s0 The workaround is \s-1NOTZ_TIMEZONE:\s0 if a date
object has a timezone, which is the same as \s-1NOTZ_TIMEZONE,\s0 then the \s-1TZ\s0
variable will be removed before each calculation. In normal case, it would
be the same as setting \s-1TZ\s0 to \f(CW$NOTZ_TIMEZONE\fR, but some systems don't like
it, so I decided to introduce this variable. The
\&\f(CW$Class::Date::NOTZ_TIMEZONE\fR variable is set in the initialization of the
module by removing the \s-1TZ\s0 variable from the environment and querying the
tzname variable.
.SH "INTERNALS"
.IX Header "INTERNALS"
This module uses operator overloading very heavily. I've found it quite stable,
but I am afraid of it a bit.
.PP
A Class::Date object is an array reference.
.PP
A Class::Date::Rel object is an array reference, which contains month and
second information. I need to store it as an array ref, because array and month
values cannot be converted into seconds, because of our super calendar.
.PP
You can add code references to the \f(CW@Class::Date::NEW_FROM_SCALAR\fR and
\&\f(CW@Class::Date::Rel::NEW_FROM_SCALAR\fR. These arrays are iterated through when a
scalar-format date must be parsed. These arrays only have one or two values
at initialization. The parameters which the code references got are the same 
as the \*(L"new\*(R" method of each class. In this way, you can personalize the date
parses as you want.
.PP
As of 0.90, the Class::Date has been rewritten. A lot of code and design
decision has been borrowed from Matt Sergeant's Time::Object, and there will
be some incompatibility with the previous public version (0.5). I tried to
keep compatibility methods in Class::Date. If you have problems regarding
this, please drop me an email with the description of the problem, and I will
set the compatibility back.
.PP
Invalid dates are Class::Date::Invalid objects. Every method call on this
object and every operation with this object returns undef or 0.
.SH "DEVELOPMENT FOCUS"
.IX Header "DEVELOPMENT FOCUS"
This module tries to be as full-featured as can be. It currently lacks
business-day calculation, which is planned to be implemented in the 1.0.x
series.
.PP
I try to keep this module not to depend on other modules and I want this
module usable without a C compiler.
.PP
Currently the module uses the \s-1POSIX\s0 localtime function very extensively.
This makes the date calculation a bit slow, but provides a rich interface,
which is not provided by any other module. When I tried to redesign the
internals to not depend on localtime, I failed, because there are no other
way to determine the daylight savings information.
.SH "SPEED ISSUES"
.IX Header "SPEED ISSUES"
There are two kind of adjustment in this module, \s-1DST_ADJUST\s0 and
\&\s-1MONTH_BORDER_ADJUST.\s0 Both of them makes the \*(L"+\*(R" and \*(L"\-\*(R" operations slower. If
you don't need them, switch them off to achieve faster calculations.
.PP
In general, if you really need fast date and datetime calculation, don't use 
this module. As you see in the previous section, the focus of development is 
not the speed in 1.0.  For fast date and datetime calculations, use 
Date::Calc module instead.
.SH "THREAD SAFETY and MOD_PERL"
.IX Header "THREAD SAFETY and MOD_PERL"
This module is \s-1NOT\s0 thread-safe, since it uses C library functions, which
are not thread-safe. Using this module in a multi-threaded environment can
cause timezones to be messed up. I did not put any warning about it, you
have to make sure that you understand this!
.PP
Under some circumstances in a mod_perl environment, you require the Env::C
module to set the \s-1TZ\s0 variable properly before calling the time functions. I
added the \-EnvC import option to automatically load this module if it is
not loaded already. Please read the mod_perl documentation about the
environment variables and mod_perl to get the idea why it is required
sometimes:
.PP
.Vb 1
\&  http://perl.apache.org/docs/2.0/user/troubleshooting/troubleshooting.html#C_Libraries_Don_t_See_C_\|_ENV_\|_Entries_Set_by_Perl_Code
.Ve
.PP
You are sure have this problem if the \f(CW$Class::Date::NOTZ_TIMEZONE\fR variable
is set to '\s-1UTC\s0', althought you are sure that your timezone is not that. Try
\&\-EnvC in this case, but make sure that you are not using it in a
multi-threaded environment!
.SH "OTHER BUGS AND LIMITATIONS"
.IX Header "OTHER BUGS AND LIMITATIONS"
.IP "\(bu" 4
Not all date/time values can be expressed in all timezones. For example:
.Sp
.Vb 2
\&  print date("2010\-10\-03 02:00:00", "Australia/Sydney")
\&  # it will print 2010\-10\-03 03:00:00
.Ve
.Sp
No matter how hard you try you, you are not going to be able to express the
time in the example in that timezone. If you don't need the timezone
information and you want to make sure that the calculations are always
correct, please use \s-1GMT\s0 as a timezone (the 'gmdate' function can be a
shortcut for it). In this case, you might also consider turning off
\&\s-1DST_ADJUST\s0 to speed up the calculation.
.IP "\(bu" 4
I cannot manage to get the timezone code working properly on ActivePerl
5.8.0 on win \s-1XP\s0 and earlier versions possibly have this problem also. If
you have a system like this, then you will have only two timezones, the
local and the \s-1GMT.\s0 Every timezone, which is not equal to
\&\f(CW$Class::Date::GMT_TIMEZONE\fR is assumed to be local. This seems to be caused
by the win32 implementation of timezone routines. I don't really know how
to make this thing working, so I gave up this issue. If anyone know a
working solution, then I will integrate it into Class::Date, but until
then, the timezone support will not be available for these platforms.
.IP "\(bu" 4
Perl 5.8.0 and earlier versions has a bug in the strftime code on some
operating systems (for example Linux), which is timezone related. I
recommend using the strftime, which is provided with Class::Date, so don't
try to use the module without the compiled part. The module will not work
with a buggy strftime \- the test is hardcoded into the beginning of the
code. If you anyway want to use the module, remove the hardcoded \*(L"die\*(R" from
the module, but do it for your own risk.
.IP "\(bu" 4
This module uses the \s-1POSIX\s0 functions for date and
time calculations, so it is not working for dates beyond 2038 and before 1902.
.Sp
I don't know what systems support dates in 1902\-1970 range, it may not work on
your system. I know it works on the Linux glibc system with perl 5.6.1
and 5.7.2. I know it does not work with perl 5.005_03 (it may be the bug of
the Time::Local module). Please report if you know any system where it does
_not_ work with perl 5.6.1 or later.
.Sp
I hope that someone will fix this with new time_t in libc. If you really need
dates over 2038 and before 1902, you need to completely rewrite this module or
use Date::Calc or other date modules.
.IP "\(bu" 4
This module uses Time::Local, and when it croaks, Class::Date returns
\&\*(L"Invalid date or time\*(R" error message. Time::Local is different in the 5.005
and 5.6.x (and even 5.7.x) version of perl, so the following code will
return different results:
.Sp
.Vb 1
\&  $a = date("2006\-11\-11")\->clone(year => \-1);
.Ve
.Sp
In perl 5.6.1, it returns an invalid date with error message \*(L"Invali date or
time\*(R", in perl 5.005 it returns an invalid date with range check error. Both
are false if you use them in boolean context though, only the error message
is different, but don't rely on the error message in this case. It however
works in the same way if you change other fields than \*(L"year\*(R" to an invalid
field.
.SH "SUPPORT"
.IX Header "SUPPORT"
Class::Date is free software. \s-1IT COMES WITHOUT WARRANTY OF ANY KIND.\s0
.PP
If you have questions, you can send questions directly to me:
.PP
.Vb 1
\&  dlux@dlux.hu
.Ve
.SH "WIN32 notes"
.IX Header "WIN32 notes"
You can get a binary win32 version of Class::Date from Chris Winters' .ppd
repository with the following commands:
.PP
For people using \s-1PPM2:\s0
.PP
.Vb 4
\&  c:\e> ppm
\&  PPM> set repository oi http://openinteract.sourceforge.net/ppmpackages/
\&  PPM> set save
\&  PPM> install Class\-Date
.Ve
.PP
For people using \s-1PPM3:\s0
.PP
.Vb 3
\&  c:\e> ppm
\&  PPM> repository http://openinteract.sourceforge.net/ppmpackages/
\&  PPM> install Class\-Date
.Ve
.PP
The first steps in \s-1PPM\s0 only needs to be done at the first time. Next time
you just run the 'install'.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001 Szabo\*', Bala\*'zs (dLux)
.PP
All rights reserved. This program is free software; you can redistribute it 
and/or modify it under the same terms as Perl itself.
.PP
Portions Copyright (c) Matt Sergeant
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  dLux (Szabo\*', Bala\*'zs) <dlux@dlux.hu>
.Ve
.SH "MAINTAINER"
.IX Header "MAINTAINER"
.Vb 1
\&   L<http://szabgab.com/>
.Ve
.SH "CREDITS"
.IX Header "CREDITS"
.Vb 7
\&  \- Matt Sergeant <matt@sergeant.org>
\&    (Lots of code are borrowed from the Time::Object module)
\&  \- Tatsuhiko Miyagawa <miyagawa@cpan.org> (bugfixes)
\&  \- Stas Bekman <stas@stason.org> (suggestions, bugfix)
\&  \- Chris Winters <chris@cwinters.com> (win32 .ppd version)
\&  \- Benoit Beausejour <bbeausej@pobox.com>
\&    (Parts of the timezone code is borrowed from his Date::Handler module)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1).
\&\fIDate::Calc\fR\|(3pm).
\&\fITime::Object\fR\|(3pm).
\&\fIDate::Handler\fR\|(3pm).