Steffen Beyer > Date-Pcalc-6.1 > Date::Pcalc::Object

Download:
Date-Pcalc-6.1.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  2
View/Report Bugs
Module Version: 6.1   Source  

NAME ^

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

MOTTO ^

Make frequent things easy and infrequent or hard things possible

PREFACE ^

Note that you do NOT need to "use Date::Pcalc qw(...);" in addition to this module.

Simply

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

INSTEAD OF

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

with the same "qw(...)" as you would with the "Date::Pcalc" module, and then forget about "Date::Pcalc::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::Pcalc::Object->new(...);

(but you may), and should use

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

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

SYNOPSIS ^

Export tags

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

Functions

See Date::Pcalc(3) 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::Pcalc->accurate_mode([FLAG]);
  $old = Date::Pcalc->normalized_mode([FLAG]);
  $old = Date::Pcalc->number_format([NUMBER|CODEREF]);
  $old = Date::Pcalc->delta_format([NUMBER|CODEREF]);  # global default
  $old = Date::Pcalc->date_format([NUMBER|CODEREF]);   # global default
  $old = Date::Pcalc->language([LANGUAGE]);            # global default - DEPRECATED

  $old = $date->accurate_mode([FLAG]);           # is global nevertheless!
  $old = $date->normalized_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::Pcalc->new([TYPE]);
  $date = Date::Pcalc->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
  $date = Date::Pcalc->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::Pcalc->today([FLAG]);
  $date  = Date::Pcalc->now([FLAG]); # shorthand for --+
  $date  = Date::Pcalc->today_and_now([FLAG]); # <-----+
  $date  = Date::Pcalc->gmtime([time]);    # UTC/GMT
  $date  = Date::Pcalc->localtime([time]); # local time
  $delta = Date::Pcalc->tzoffset([time]);
  $date  = Date::Pcalc->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::Pcalc->mktime();    # same as "$time = CORE::time();"
  $time = Date::Pcalc->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::Pcalc->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::Pcalc::Object qw(:all);

  Date::Pcalc->date_format(3);

  $date = 0;
  while (!$date)
  {
      print "Please enter the date of your birthday (day-month-year): ";
      $date = Date::Pcalc->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::Pcalc(3), Date::Calc::Util(3), Date::Pcalendar(3), Date::Pcalendar::Year(3), Date::Pcalendar::Profiles(3).

VERSION ^

This man page documents "Date::Pcalc::Object" version 6.1.

AUTHOR ^

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

COPYRIGHT ^

Copyright (c) 2000 - 2009 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.

syntax highlighting: