NAME
    Class::Date - Class for easy date and time manipulation

SYNOPSIS
      use Class::Date qw(:errors date localdate gmdate now -DateParse);
  
      # creating absolute date object (local time)
      $date = new Class::Date [$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 = new Class::Date [$year,$month,$day,$hour,$min,$sec],1;
      $date = gmdate "2001-11-12 17:13";
      ...

      # creating relative date object
      # (normally you don't need to create this object explicitly)
      $reldate = new Class::Date::Rel "3Y 1M 3D 6h 2m 4s";
      $reldate = new Class::Date::Rel "6Y";
      $reldate = new Class::Date::Rel $secs;  # secs
      $reldate = new Class::Date::Rel [$year,$month,$day,$hour,$min,$sec];
      $reldate = new Class::Date::Rel { year => $year, month => $month, day => $day,
        hour => $hour, min => $min, sec => $sec };
      $reldate = new Class::Date::Rel "2001-11-12 07:13:12";
      $reldate = new Class::Date::Rel "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->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)

      ($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

      # date format changes
      {
        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 ... 
      }

      # 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")+'1M'; # will print 2001-03-03
      $Class::Date::MONTH_BORDER_ADJUST = 1;
      print date("2001-01-31")+'1M'; # 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+'3Y 2D';   # 3 Years and 2 days
      $date3    = $date+[1,2,3];   # $date plus 1 year, 2 months, 3 days
      $date4    = $date+'3-1-5'    # $date plus 3 years, 1 months, 5 days

      $new_date = $date-$reldate;
      $date2    = $date-'3Y';      # 3 Yearss
      $date3    = $date-[1,2,3];   # $date minus 1 year, 2 months, 3 days
      $date4    = $date-'3-1-5'    # $date minus 3 years, 1 month, 5 days

      $new_reldate = $date1-$date2;
      $reldate2 = Class::Date->new('2000-11-12')-'2000-11-10';
      $reldate3    = $date3-'1977-11-10';

      $days_between = (Class::Date->new('2001-11-12')-'2001-07-04')->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") + '1M' - '1M'; # gives "2001-02-01"
      print date("2000-02-29") + '1Y' - '1Y'; # 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;

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.

    You can use "+", "-", "<" and ">" operators as with native perl data
    types.

USAGE
    If you want to use a date object, you need to do the following:

      - create a new object
      - do some operations (+, -, comparison)
      - get result back

  Creating a new date object

    You can create a date object by the "date", "localdate" or "gmdate"
    function, or by calling the Class::Date constructor.

    "date" and "Class::Date->new" are equivalent, both has two arguments:
    The date and if the second argument is true then the date interpreted as
    GMT not local.

      $date1= date [2000,11,12];
      $date2= Class::Date->new([2000,06,11,13,11,22],1);

    "localdate $x" is equivalent to "date $x", "gmdate $x" is equivalent to
    "date $x,1":

      $date1= localdate [2000,11,12];
      $date2= gmdate [2000,4,2,3,33,33];

      $date = localdate(time);

    The format of the accepted input date can be:

    [$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)

    { year => $year, month => $month, day => $day, hour => $hour, min =>
    $min, sec => $sec }
        A hash reference with the same 6 elements as above.

    "YYYYMMDDhhmmss"
        A mysql-style timestamp value, which consist of at least 14 digit.

    "973897262"
        A valid 32-bit integer: This is parsed as a unix time.

    "YYYY-MM-DD hh::mm:ss"
        A standard ISO(-like) date format. Additional ".fraction" part is
        ignored, ":ss" can be omitted.

    additional input formats
        You can specify "-DateParse" as an import parameter, e.g:

          use Class::Date qw(date -DateParse);

        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.

  Operations

    addition
        You can add the following to a Class::Date object:

          - a valid Class::Date::Rel object
          - anything, that can be used for creating a new Class::Date::Rel object

        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:

          $date= Class::Date->new('2001-12-11')+Class::Date::Rel->new('3Y');

        is the same as:

          $date= date('2001-12-11')+'3Y';

        You can provide a Class::Date::Rel object in the following form:

        array ref
            The same format as seen in Class::Date format, except the
            default values are different: all zero.

        hash ref
            The same format as seen in Class::Date format, except the
            default values are different: all zero.

        "973897262"
            A valid 32-bit integer is parsed as seconds.

        "YYYY-MM-DD hh::mm:ss"
            A standard ISO date format, but this is parsed as relative date
            date and time, so month, day and year can be zero (and defaults
            to zero).

        "12Y 6M 6D 20h 12m 5s"
            This special string can be used if you don't want to use the ISO
            format. This string consists of whitespace separated tags, each
            tag consists of a number and a unit. The units can be:

              Y: year
              M: month
              D: day
              h: hour
              m: min
              s: sec

            The number and unit must be written with no space between them.

    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:

          $reldate=$date1-$date2;
          $reldate=date('2001-11-12 12:11:07')-date('2001-10-07 10:3:21');

        In this case, the "month" field of the $reldate object will be 0,
        and the other fields will contain the difference between two dates;

    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.

        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).

          if ( date('2001-11-12') > date('2000-11-11') ) { ... }

        or

          if ( date('2001-11-12') > '2000-11-11' ) { ... }

    truncate
        You can chop the time value from this object (set hour, min and sec
        to 0) with the "truncate" or "trunc" method. It does not modify the
        specified object, it returns with a new one.

    clone
        You can create new date object based on an existing one, by using
        the "clone" method. Note, this DOES NOT modify the base object.

          $new_date = $date->clone( year => 2001, hour => 14 );

        The valid keys are: year, _year, month, mon, _month, _mon, day,
        mday, day_of_month, hour, min, minute, sec, second.

        There is a "set" method, which does the same as the "clone", it
        exists only for compatibility.

    Operations with Class::Date::Rel
        The Class::Date::Rel object consists of a month part and a day part.
        Most people only use the "day" part of it. If you use both part,
        then you can get these parts with the "sec_part" and "mon_part"
        method. If you use "sec", "month", 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...

        If you use Class::Date::Rel in an expression with other Class::Date
        or Class::Date::Rel objects, then it does what is expected:

          date('2001-11-12')+'1M' will be '2001-12-12'

        and

          date('1996-02-11')+'2M' will be '1996-04-11'

  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.

  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:

      $a = date($input_date);
      if ($a) { # valid date
          ...
      } else { # invalid date
          ...
      }

    Note even the date is invalid, the expression "defined $a" always
    returns true, so the following is wrong:

      $a = date($input_date);
      if (defined $a) ... # WRONG!!!!

    You can test the error by getting the $date->error value. You might
    import the ":errors" tag:

      use Class::Date qw(:errors);

    Possible error values are:

    E_OK
        No errors.

    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.

    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
        $Class::Date::RANGE_CHECK is not set, then these date values are
        automatically converted to a valid date: 2001-03-03, but the
        $date->error value are set to E_RANGE. If $Class::Date::RANGE_CHECK
        is set, then a date "2001-02-31" became invalid date.

    E_UNPARSABLE
        This error is set, when the constructor cannot be created from a
        scalar, e.g:

          $a = date("4kd sdlsdf lwekrmk");

    E_UNDEFINED
        This error is set, when you want to create a date object from an
        undefined value:

          $a = new Class::Date (undef);

        Note, that localdate(undef) will create a valid object, because it
        calls $Class::Date(time).

DST_ADJUST
    $DST_ADJUST is an importable variable, and is a very important
    configuration option.

    If it is set to true (default), then it adjusts the date and time when
    the operation switches the border of DST. You will see the difference if
    you run this code:

      $Class::Date::DST_ADJUST=0;
      for (my $date=localdate("2000-06-11");$date<"2001-4-5";$date+='1D') {
        print $date."\n";
      }

      $Class::Date::DST_ADJUST=1;
      for (my $date=localdate("2000-06-11");$date<"2001-4-5";$date+='1D') {
        print $date."\n";
      }

MONTHS AND YEARS
    If you add or subtract "months" and "years" 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

      date("2001-01-31") + '1M' - '1M' != "2001-01-31"

    This problem can occur only with months and years, because others can
    easily be converted to seconds.

MONTH_BORDER_ADJUST
    $MONTH_BORDER_ADJUST 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 "2001-01-31" will result "2001-02-31", and this is
    an invalid date.

    When $MONTH_BORDER_ADJUST is false, this result simply normalized, and
    becomes "2001-03-03". This is the default behaviour.

    When $MONTH_BORDER_ADJUST is true, this result becomes "2001-02-28". So
    when the date overflows, then it returns the last day insted.

    Both settings keeps the time information.

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 "Date.pm" whereever your perl
    compiler searches for it. You must make a "Class" directory for it
    before.

    In Debian GNU/Linux system (woody) , a good choice can be the following:

      mkdir /usr/local/share/perl/5.6.1/Class
      cp Date.pm /usr/local/share/perl/5.6.1/Class

    And the module will work.

    You can use the $WARNINGS switch to switch off the complains about the
    missing XS part from your perl program:

        BEGIN { $Class::Date::WARNINGS=0; }
        use Class::Date;
        ...

INTERNALS
    This module uses operator overloading very heavily. I've found it quite
    stable, but I am afraid of it a bit.

    A Class::Date object is an array reference.

    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.

    You can add code references to the @Class::Date::NEW_FROM_SCALAR and
    @Class::Date::Rel::NEW_FROM_SCALAR. 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 "new" method of each class. In this way, you can
    personalize the date parses as you want.

    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.

    Invalid dates are Class::Date::Invalid objects. Every method call on
    this object and every operation with this object returns undef or 0.

DEVELOPMENT FOCUS
    For 1.0.x, the first goal is to fix the upcoming bugs and for make it
    work in more and more platform.

    For later releases (2.0), I plan a major rewrite, which will keep only
    the user interface, but can be used with several existing backends for
    date calculation, formatting and date parsing. Some kind of plugins
    system can keep this module as is: a 'general date and time type' for
    perl. With the plugin system, a user have more control over speed,
    memory usage and environmental restrictions.

    E.g. Someone, who doesn't want to use the huge POSIX module, can use the
    internal strftime function, who doesn't want to use (or cannot use) a C
    compiler in a specific environment, can use it from the POSIX module.

    If someone wants to use Date::Calc as a date manipulation backend,
    because it is much faster than the localtime() / gmtime() based internal
    routines, and this module is available, then he can use it.

SPEED ISSUES
    There are two kind of adjustment in this module, DST_ADJUST and
    MONTH_BORDER_ADJUST. Both of them makes the "+" and "-" operations
    slower. If you don't need them, switch them off to achieve faster
    calculations.

    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 until 1.0. For fast date and datetime
    calculations, use Date::Calc instead.

BUGS AND LIMITATIONS
    *   This module uses the POSIX functions for date and time calculations,
        so it is not working for dates beyond 2038 and before 1902.

        I don't know what systems support dates in 1902-1970 range, it may
        not work on your system because. 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.

        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.

        Note: I can use

    *   This module uses Time::Local, and when it croaks, Class::Date
        returns "Invalid date or time" error message. Time::Local is
        different in the 5.005 and 5.6.x version of perl, so the following
        code will return different results:

          $a = date("2006-11-11")->clone(year => -1);

        In perl 5.6.1, it returns an invalid date with error message "Invali
        date or time", 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 "year" to an invalid field.

SUPPORT
    Class::Date is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

    If you have questions, you can send it to the Class::Date mailing list:

      class-date@lists.dlux.hu
  
    You can subscribe to this list by a web-interface:

      http://lists.dlux.hu/wws/info/class-date

WIN32 notes
    Class::Date works in win32 with no known problems. You can acquire and
    compile yourself from source or you can get the binary from the Chris
    Winters' .ppd repository with the following commands:

      c:\> ppm
      PPM> set repository oi http://openinteract.sourceforge.net/ppmpackages/
      PPM> set save
      PPM> install Class-Date

    The first two steps in PPM only need to be done at the first time. Next
    time you just run the 'install'.

COPYRIGHT
    Copyright (c) 2001 Szabó, Balázs (dLux)

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

    Portions Copyright (c) Matt Sergeant

AUTHOR
      dLux (Szabó, Balázs) <dlux@dlux.hu>

CREDITS
      - 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)

SEE ALSO
    perl, Date::Calc, Time::Object.