DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Date::Calc::Object

NAME

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

MOTTO

Make frequent things easy and infrequent or hard things possible

PREFACE

Note that you do NOT need to ``use Date::Calc qw(...);'' in addition to this module.

Simply

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

INSTEAD OF

  use Date::Calc qw(...);

with the same ``qw(...)'' as you would with the ``Date::Calc'' module, and then forget about ``Date::Calc::Object'' altogether.

The rest of your existing code doesn't change at all.

Note also that in order to create a new date object, you do not need to use

  $date_object = Date::Calc::Object->new(...);

(but you may), and should use

  $date_object = Date::Calc->new(...);

instead (saves you some typing and is a trifle faster).

SYNOPSIS

Export tags

  :all  -  all functions from Date::Calc
  :aux  -  auxiliary functions shift_*
  :ALL  -  both :all and :aux

Functions

See the Date::Calc(3) manpage for a list of available functions.

  $year                          = shift_year(\@_);
  ($year,$mm,$dd)                = shift_date(\@_);
  ($hrs,$min,$sec)               = shift_time(\@_);
  ($year,$mm,$dd,$hrs,$min,$sec) = shift_datetime(\@_);

Methods

  $old = Date::Calc->accurate_mode([FLAG]);
  $old = Date::Calc->number_format([NUMBER|CODEREF]);
  $old = Date::Calc->delta_format([NUMBER|CODEREF]);  # global default
  $old = Date::Calc->date_format([NUMBER|CODEREF]);   # global default
  $old = Date::Calc->language([LANGUAGE]);            # global default
  $old = $date->accurate_mode([FLAG]);           # is global nevertheless!
  $old = $date->number_format([NUMBER|CODEREF]); # is global nevertheless!
  $old = $date->delta_format([NUMBER|CODEREF]);  # individual override
  $old = $date->date_format([NUMBER|CODEREF]);   # individual override
  $old = $date->language([LANGUAGE]);            # individual override
  $flag = $date->is_delta();
  $flag = $date->is_date();
  $flag = $date->is_short(); # i.e., has no time part
  $flag = $date->is_long();  # i.e., 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);
  $targetdate->copy(@list);
  ($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([FLAG]);
  $date  = Date::Calc->now([FLAG]); # shorthand for --+
  $date  = Date::Calc->today_and_now([FLAG]); # <-----+
  $date  = Date::Calc->gmtime([time]);    # UTC/GMT
  $date  = Date::Calc->localtime([time]); # local time
  $delta = Date::Calc->tzoffset([time]);
  $date  = Date::Calc->time2date([time]); # UTC/GMT
  $date->today([FLAG]);         # updates the date part only
  $date->now([FLAG]);           # updates the time part only
  $date->today_and_now([FLAG]); # updates both date and time
  $date->gmtime([time]);        # updates both date and time (UTC/GMT)
  $date->localtime([time]);     # updates both date and time (local time)
  $delta->tzoffset([time]);     # updates both date and time
  $date->time2date([time]);     # updates both date and time (UTC/GMT)
  $time = Date::Calc->mktime();    # same as "$time = CORE::time();"
  $time = Date::Calc->date2time(); # same as "$time = CORE::time();"
  $time = $date->mktime();      # converts into Unix time (local time)
  $time = $date->date2time();   # converts into Unix time (UTC/GMT)
  $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|CODEREF]);
  $string = $date->string([NUMBER|CODEREF][,LANGUAGE]);
  $delta->normalize(); # renormalizes a delta vector

Overloaded Operators

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

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
  $comp = $date1 <=> $date2; # 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
  $comp = $date1 cmp $date2; # compares both date and time

Note that you can of course also compare two deltas, but not a date and a delta!

  ##################################################
  # 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) {

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;

Unary Minus:

  $delta2 = -$delta1;

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;

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

DESCRIPTION

EXAMPLES

  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];
  }
  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"; }

For more examples, see the ``examples'' subdirectory in this distribution, and their descriptions in the file ``EXAMPLES.txt''.

SEE ALSO

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

VERSION

This man page documents ``Date::Calc::Object'' version 5.4.

AUTHOR

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

COPYRIGHT

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

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!

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.