NAME

SYNOPSIS

  use Date::Piece qw(date);

  my $date = date('2007-11-22');
  my $time = $date->at('16:42:35');

  print $time, "\n"; # is a Time::Piece

You can also start from a Time::Piece object.

  use Time::Piece;
  use Date::Piece;

  my $time = localtime;
  my $date = $time->date; # also ymd()

  $date+=7;
  # seven days later
  print $date, "\n";

  # seven days later at the original time
  print $date->at($time), "\n";

ABOUT

This is useful for constructs such as "tomorrow", "yesterday", "this time tomorrow", "one week from today", "one month later", "my 31st birthday", and various other not-necessarily-numeric intervals on the arbitrary and edge-case-laden division of time known by most earthlings as "the calendar." That is, adding days or months is analogous to counting squares or turning pages on a calendar.

This module extends Date::Simple and connects it to Time::Piece. See Date::Simple for more details.

Immutable

This does not appear to be true with constructs such as "$date++" or "$date+=7", but what is actually happening is that perl treats the variable as an lvalue and assigns the new object to it. Thus, the following is true:

  my $also_date = my $date = today;
  $date++;
  $date > $also_date;

Validation

Convenient Syntax

When loaded as -MDate::Piece with perl -e (and/or -E in 5.10), these extremely short versions are exported by default:

  years  => 'Y',
  months => 'M',
  weeks  => 'W',
  date   => 'D',
  today  => 'CD', # mnemonic: Current Date

You may unimport any imported functions with the 'no Date::Piece' directive.

Functions

  my $today = today;
  my $tomorrow = today + 1;

  my $new_year_is_coming = date('2007-12-31');

  my $d = date($year, $month, $day);

  no Date::Piece;

Methods

  $date->Y;

  $date->M;

  $date->mon;

  $date->monthname;

  $date->D;

  my $dow = $date->iso_dow;

  my $wday = $date->iso_wday;

Setting the Time on a Date

  my $timepiece = $date->at($time);

Endpoints

  my $start = $date->start_of_year;

  my $end = $date->end_of_year;

  my $start = $date->start_of_month;

  my $end = $date->end_of_month;

  my $num = $date->days_in_month;

  my $bool = $date->leap_year;

  my @list = $date->thru($other_date);

  my $subref = $date->iterator($other_date);
  while(my $day = $subref->()) {
    # do something with $day
  }

Fuzzy Math

  $date = adjust_day_of_month($y, $m, $maybe_day);

  my $shifted = $date->add_months($n);

  my $shifted = $date->add_years($n);

Year, Month, and etc "units"

  use Date::Piece qw(today years);
  my $distant_future = today + 10*years;

  perl -MDate::Piece -e 'print CD+10*Y, "\n";'

The unit objects stringify as e.g. '10years'.

You may also divide time units by a number as long as the result is an integer. You may not use units as a divisor.

Any math done on these units which yields other than an integer will throw a run-time error.

Also available are 'centuries' and 'days' (the latter is convenient as a stricture to ensure that your days are integers.)

Conversion between these units only makes sense for centuries => years and weeks => days, but is currently not available.

  $date = $date->_add($thing);

  $date = $date->_subtract($thing);

Examples

  use Date::Piece qw(date today years months weeks);
  use Time::Piece;

Turning 40 is pretty arbitrary, but alarming!

  my $bd = date('1970-12-02');
  my $big40 = $bd+40*years;

  $SIG{ALRM} = sub { print "dude!  You're 'old' now.\n"; exit; }
  my $eggtimer = localtime - $big40->at('06:57');
  alarm($eggtimer);

  while(1) {
    my $countdown = $big40-today;
    print "$countdown days till the top of the hill\n";
    sleep(3600*24);
  }

Wake me when the ball drops (in my time zone.)

  my $date = today+1*years;
  $date = $date->start_of_year;
  $SIG{ALRM} = sub { print "Happy new year!\n"; exit; }
  alarm(localtime - $date->at('0s'));

Constructor

AUTHOR

http://scratchcomputing.com/

BUGS

If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

NO WARRANTY

LICENSE