
=head1 NAME

Date::Calc::Object - Object-oriented add-on for Date::Calc with overloaded operators

=head1 MOTTO

Make frequent things easy and infrequent or hard things possible

=head1 PREFACE

Note that you do not need to "C<use Date::Calc qw(...);>"
in addition to this module.

Simply "C<use Date::Calc::Object qw(...);>" B<INSTEAD> of
"C<use Date::Calc qw(...);>", with the same "C<qw(...)>"
as you would with the Date::Calc module, and then forget
about "Date::Calc::Object" altogether. The rest of your
existing code (if any) doesn't change at all.

Note also that in order to create a new date object,
you do not need to use
"C<$date_object = Date::Calc::Object-E<gt>new(...);>"
(but you may), and should use
"C<$date_object = Date::Calc-E<gt>new(...);>"
instead (saves you some typing).

=head1 SYNOPSIS

=head2 Functions

See L<Date::Calc(3)> for a list of available functions.

=head2 Methods

  $old = Date::Calc->accurate_mode([FLAG]);
  $old = Date::Calc->number_format([NUMBER]);
  $old = Date::Calc->delta_format([NUMBER]);
  $old = Date::Calc->date_format([NUMBER]);

  $old = $date->accurate_mode([FLAG]);   # is global nevertheless!
  $old = $date->number_format([NUMBER]); # is global nevertheless!
  $old = $date->delta_format([NUMBER]);  # is global nevertheless!
  $old = $date->date_format([NUMBER]);   # is global nevertheless!

  $flag = $date->is_delta();
  $flag = $date->is_date();
  $flag = $date->is_short(); # has no time part
  $flag = $date->is_long();  # has time part
  $flag = $date->is_valid();

  $date = Date::Calc->new([TYPE]);
  $date = Date::Calc->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
  $date = Date::Calc->new($arrayref);
  $newdate = $somedate->new([TYPE]);
  $newdate = $somedate->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
  $newdate = $somedate->new($arrayref);

  $datecopy = $date->clone();
  $targetdate->copy($sourcedate);
  $targetdate->copy($arrayref);

  ($year,$month,$day) = $date->date([TYPE]);
  ($year,$month,$day) = $date->date([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
  ($year,$month,$day) = $date->date($arrayref);
  ([$hrs,$min,$sec])  = $date->time([TYPE]);
  ($hrs,$min,$sec)    = $date->time([TYPE,]HRS,MIN,SEC);
  ([$hrs,$min,$sec])  = $date->time($arrayref);

  ($year,$month,$day,$hrs,$min,$sec) =
      $date->datetime([TYPE]);
  ($year,$month,$day,$hrs,$min,$sec) =
      $date->datetime([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);

  $date = Date::Calc->today();
  $date = Date::Calc->now(); # shorthand for --+
  $date = Date::Calc->today_and_now(); # <-----+

  $date->today();         # updates the date part only
  $date->now();           # updates the time part only
  $date->today_and_now(); # updates both date and time

  $year    = $date->year([YEAR]);
  $month   = $date->month([MONTH]);
  $day     = $date->day([DAY]);
  $hours   = $date->hours([HRS]);
  $minutes = $date->minutes([MIN]);
  $seconds = $date->seconds([SEC]);

  $number = $date->number([NUMBER]);
  $string = $date->string([NUMBER]);

=head2 Overloaded Operators

  #####################################################
  # Scalar operands are always converted into a delta #
  # vector with that many days, i.e., [1,0,0,SCALAR]  #
  #####################################################

=head2 Comparison Operators:

  if ($date1 <  $date2) { # compares date part only
  if ($date1 <= $date2) { # compares date part only
  if ($date1 >  $date2) { # compares date part only
  if ($date1 >= $date2) { # compares date part only
  if ($date1 == $date2) { # compares date part only
  if ($date1 != $date2) { # compares date part only

  if ($delta1 == $delta2) { # compares date part only
  if ($delta1 != $delta2) { # compares date part only

  if ($date1 lt $date2) { # compares both date and time
  if ($date1 le $date2) { # compares both date and time
  if ($date1 gt $date2) { # compares both date and time
  if ($date1 ge $date2) { # compares both date and time
  if ($date1 eq $date2) { # compares both date and time
  if ($date1 ne $date2) { # compares both date and time

  if ($delta1 eq $delta2) { # compares both date and time
  if ($delta1 ne $delta2) { # compares both date and time

  ##################################################
  # Default TYPE for array refs in comparisons is: #
  # Same as other operand                          #
  ##################################################

  if ([2000,4,1] == $date) {
  if ($today > [2000,4,1]) {

  if ($now ge [2000,3,26,2,0,0]) {

  if ($delta == [18,0,0]) {
  if ($delta == -1) {

=head2 Plus:

  $date2 = $date1 + $delta;
  $date2 = $delta + $date1;
  $date += $delta;
  $this = $date++;
  $next = ++$date;

  $delta3 = $delta1 + $delta2;
  $delta1 += $delta2;
  $delta += $date; # beware of implicit type change!
  $delta++;
  ++$delta;

  #####################################################
  # Default TYPE for array refs in '+' operations is: #
  # Opposite of other operand                         #
  #####################################################

  $date2 = [2000,3,26] + $delta;
  $date2 = $date1 + [+1,0,0];
  $date2 = [0,0,-1] + $date1;
  $date2 = $date1 + 1;
  $date += [0,0,+1];
  $date += 2;

  $delta3 = [1,+1,0,-1] + $delta2;
  $delta3 = $delta1 + [1,0,0,+1];
  $delta3 = $delta1 + 1;
  $delta += [1,0,+1,0];
  $delta += [2000,3,26]; # beware of implicit type change!
  $delta += 7;

=head2 Unary Minus:

  $delta2 = -$delta1;

=head2 Minus:

  $delta = $date2 - $date1;
  $date2 = $date1 - $delta;
  $date -= $delta;
  $date2 -= $date1; # beware of implicit type change!
  $this = $date--;
  $prev = --$date;

  $delta3 = $delta2 - $delta1;
  $delta2 -= $delta1;
  $delta--;
  --$delta;

  #####################################################
  # Default TYPE for array refs in '-' operations is: #
  # Always a date                                     #
  #####################################################

  $delta = $today - [2000,3,26];
  $delta = [2000,4,1] - $date;
  $date2 = [2000,3,26] - $delta;
  $date2 = $date1 - [1,0,0,+7];
  $date2 = $date1 - 7;
  $date -= [1,0,0,+1]; # better add [0,0,-1] instead!
  $date2 -= [2000,3,26]; # beware of implicit type change!
  $date2 -= 1;

  $delta3 = [1,0,+1,0] - $delta1;
  $delta3 = $delta2 - [1,0,0,-1];
  $delta -= [1,0,0,+1];
  $delta -= 7;

=head2 Miscellaneous Operators:

  $string = "$date";
  $string = "$delta";

  print "$date\n";
  print "$delta\n";

  if ($date) { # date is valid
  if ($delta) { # delta is valid

  $days = abs($date);
  $diff = abs($delta); # can be negative!

  $diff = abs(abs($delta)); # always positive

=head1 DESCRIPTION

=over 2

=item *

FLAG

"FLAG" is either 0 (for "false") or 1 (for "true").

=item *

TYPE

"TYPE" is 0 for a regular date and 1 for a delta vector (a list of
year, month, day and optionally hours, minutes and seconds offsets).

=item *

NUMBER

"NUMBER" is a number between 0 and 2 (for "number_format()" and "number()")
or between 0 and 3 (for "delta_format()", "date_format()" and "string()"),
indicating which of the three/four predefined formats, respectively,
should be used for converting a date into numeric representation
(needed for comparing dates, for instance) or string representation.

Format #0 is the simplest (and fastest), and in the case of dates (not
delta vectors), it has the additional advantage of being sortable (and
of complying with S<ISO 8601>). (The numeric formats are always sortable.)

The other formats are increasingly sophisticated in accordance with their
number.

If a number outside of the permitted range is specified, the default
format #0 is used instead.

=item *

Storage

Dates and delta vectors always comprise either 3 or 6 values: Year,
month, day plus (optionally) hours, minutes and seconds.

Actually, an additional (seventh) value (the "TYPE") indicates whether
the object is a date or a delta vector. This flag is stored in the
first element (with index zero) of the array.

If you do not need the time values, omit them, this will speed up
calculations a little (uses different (faster) functions internally).

=item *

Invalid Dates

Only "new()" allows to create objects containing possibly invalid
dates (needed for reading in and evaluating user input, for example).

=item *

Usage

The methods

        accurate_mode()
        number_format()
        delta_format()
        date_format()
        date()
        time()
        datetime()
        year()
        month()
        day()
        hours()
        minutes()
        seconds()

are used for reading as well as for setting attributes. They simply
return the values in question if they are called without parameters.

The methods

        accurate_mode()
        number_format()
        delta_format()
        date_format()

always return the previous value if a new value is set. This allows
you to change these values temporarily and to restore their old value
afterwards more easily (but you can also override the "format" settings
directly when calling the "number()" or "string()" method).

The methods

        date()
        time()
        datetime()
        year()
        month()
        day()
        hours()
        minutes()
        seconds()

always return the new values when the corresponding values have
been changed.

The method "date()" NEVER returns the time values (hours, minutes,
seconds) even if they have just been set using this method (which
the method optionally allows). Otherwise it would be very hard to
predict the exact number of values it returns, which might lead
to errors (wrong number of parameters) elsewhere in your program.

The method "datetime()" ALWAYS returns the time values (hours,
minutes, seconds) even if the object in question lacks a time
part. In that case, zeros are returned for hours, minutes and
seconds instead (but the stored time part is left unchanged,
whether it exists or not).

If you do not provide values for hours, minutes and seconds when
using the method "date()" to set the values for year, month and
day, the time part will not be changed (whether it exists or not).

If you do not provide values for hours, minutes and seconds when
using the method "datetime()" to set the values for year, month
and day, the time part will be filled with zeros (the time part
will be created if necessary).

If the object is short, i.e., if it does not have any time values,
the method "time()" returns an empty list.

If the object is short and the methods "hours()", "minutes()" or
"seconds()" are used to set any of these time values, the object
is automatically promoted to the "long" form, and the other two
time values are filled with zeros.

The following methods can also return "undef" under certain
circumstances:

        is_delta()
        is_date()
        is_short()
        is_long()
        is_valid()
        hours()
        minutes()
        seconds()
        number()
        string()

The "is_*()" predicate methods return "undef" if the object in
question does not have the expected internal structure. This can
happen for instance when you create an empty object with "new()".

When called without parameters, the methods "hours()", "minutes()"
and "seconds()" return "undef" if the object in question does not
have a time part.

The methods "number()" and "string()" return "undef" if the object
in question is not valid (i.e., if "is_valid()" returns "undef" or
false).

And finally, the methods

        copy()
        today()
        now()
        today_and_now()

return the object reference of the (target) object in question
for convenience.

=item *

Accurate Mode

The method "accurate_mode()" controls the internal flag which
determines which of two modes of operation is used.

When set to true (the default at startup), delta vectors are
calculated to give the exact difference in days between two
dates. The "year" and "month" entries in the resulting delta
vector are always zero in this case.

If "accurate mode" is switched off (when the corresponding
flag is set to false), delta vectors are calculated with
year and month differences.

E.g., the difference between C<[1999,12,6]> and C<[2000,6,24]>
is C<[+0 +0 +201]> (plus 201 days) in accurate mode and
C<[+1 -6 +18]> (plus one year, minus 6 months, plus 18 days)
when accurate mode is switched off.

Because years and months have varying lengths in terms of days,
the latter is less accurate than the former because it depends
on the context of the two dates of which it represents the
difference. Added to a different date, the latter delta vector
may yield a different offset in terms of days.

Note also that - for the same reason - you cannot take the
absolute value ("C<abs()>") of a delta vector if the delta
vector contains non-zero values for "year" and/or "month"
(see next section below for more details).

Example:

The difference between C<[2000,1,1]> and C<[2000,3,1]> is
C<[+0 +0 +60]> in accurate mode and C<[+0 +2 +0]> else (one
could call this "year-month-day mode" or "YMD mode" for short).

When added to the date C<[2000,4,1]>, the "accurate" delta
vector yields the date C<[2000,5,31]>, whereas the other delta
vector yields the date C<[2000,6,1]>.

Moreover, when added to the date C<[1999,1,1]>, the "accurate"
delta vector yields the date C<[1999,3,2]>, whereas the "inaccurate"
delta vector yields the date C<[1999,3,1]>.

Depending on what you want, the one or the other mode may suit
you better.

=item *

Absolute Value

Note that "C<abs($date)>" and "C<abs($delta)>" are just shorthands
for "C<$date-E<gt>number()>" and "C<$delta-E<gt>number()>".

The operator "C<abs()>", when applied to a date or delta vector,
returns the corresponding number of days (except for one special
case, see below).

In the case of dates, this is the number of days since the
1st of January 1 A.D. (by extrapolating the Gregorian calendar
back beyond its "natural" limit of 1582 A.D.) plus one.

(I.e., the absolute value of the 1st of January 1 A.D. is one.)

Special case:

If the "NUMBER" or "number_format()" is set to 0 (the default
setting), the absolute value of a date is "yyyymmdd", i.e., the
number in which the uppermost four digits correspond to the year,
the next lower two digits to the month and the lowermost two digits
to the day.

In the case of delta vectors, the absolute value is simply the
difference in days, i.e., the value of the "days" entry in the
given delta vector.

Note that the absolute value of a delta vector can therefore be
negative!

If you want a positive value in all cases, apply the "C<abs()>"
operator again, i.e., "C<$posdiff = abs(abs($delta));>".

If the delta vector contains values for "year" and/or "month",
a representation in days cannot be calculated, because years
and months do not have fixed equivalents in days. If nevertheless
you attempt to calculate the absolute value of such a delta vector,
a fatal error occurs. (See also the section on "Accurate Mode"
immediately above!)

If the date or delta vector has a time part, the time is returned
as a fraction of a full day after the decimal point as follows:

If the "NUMBER" or "number_format()" is set to 0 (the default
setting) or 1, this fraction is simply ".hhmmss", i.e., the
two digits after the decimal point represent the hours, the
next two digits the minutes and the last two digits the seconds.

Note that you cannot simply add and subtract these values to
yield meaningful dates or deltas again, you can only use them
for comparisons (equal, not equal, less than, greater than,
etc.). If you want to add/subtract, read on:

Only when the "NUMBER" or "number_format()" is set to 2, this
fraction will be the equivalent number of seconds (i.e.,
C<(((hours * 60) + minutes) * 60) + seconds>) divided by the
number of seconds in a full day (i.e., C<24*60*60 = 86400>),
or C<0/86400>, C<1/86400>, ... , C<86399/86400>.

You can safely perform arithmetics with these values as far
as the internal precision of your vendor's implementation
of the C run-time library (on which Perl depends) will permit.

=item *

Languages

Note that this module is completely transparent to the setting
of a language in Date::Calc. I.e., you can set a different
language in Date::Calc and all dates printed by this module
will automatically be in that language.

=back

=head1 EXAMPLES

=over 3

=item 1)

  # Switch to summer time:
  $now = Date::Calc->now();
  if (($now ge [2000,3,26,2,0,0]) and
      ($now lt [2000,3,26,3,0,0]))
  {
      $now += [0,0,0,1,0,0];
  }

=item 2)

  use Date::Calc::Object qw(:all);

  Date::Calc->date_format(3);

  $date = 0;
  while (!$date)
  {
      print "Please enter the date of your birthday (day-month-year): ";
      $date = Date::Calc->new( Decode_Date_EU( scalar(<STDIN>) ) );
      if ($date)
      {
          $resp = 0;
          while ($resp !~ /^\s*[YyNn]/)
          {
              print "Your birthday is: $date\n";
              print "Is that correct? (yes/no) ";
              $resp = <STDIN>;
          }
          $date = 0 unless ($resp =~ /^\s*[Yy]/)
      }
      else
      {
          print "Unable to parse your birthday. Please try again.\n";
      }
  }

  if ($date + [18,0,0] <= [Today()])
      { print "Ok, you are over 18.\n"; }
  else
      { print "Sorry, you are under 18!\n"; }

=back

=head1 SEE ALSO

Date::Calc(3), Date::Calendar(3),
Date::Calendar::Year(3), Date::Calendar::Profiles(3).

=head1 VERSION

This man page documents "Date::Calc::Object" version 5.0.

=head1 AUTHOR

  Steffen Beyer
  mailto:sb@engelschall.com
  http://www.engelschall.com/u/sb/download/

=head1 COPYRIGHT

Copyright (c) 2000 by Steffen Beyer. All rights reserved.

=head1 LICENSE

This package is free software; you can redistribute it and/or
modify it under the same terms as Perl itself, i.e., under the
terms of the "Artistic License" or the "GNU General Public License".

Please refer to the files "Artistic.txt" and "GNU_GPL.txt"
in this distribution for details!

=head1 DISCLAIMER

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.

