NAME

  Date::Business - fast calendar and business date calculations

SYNOPSIS

  All arguments to the Date::Business constructor are optional.

  # simplest case, default is today's date (localtime)
  $d = new Date::Business();           

  # initialize with date string, 
  # offset in business days is optional
  $d = new Date::Business(DATE => '19991124' [, OFFSET => <integer>]); 

  # initialize with another Date::Business object
  # offset in business days is optional
  $x = new Date::Business(DATE => $d [, OFFSET => <integer>]);         

  # initialize with holiday function (see Holidays, below)
  $d = new Date::Business(HOLIDAY => \&holiday); 

  # force weekends/holidays to the previous or next business day
  $d = new Date::Business(FORCE => 'prev'); # Friday (usually)
  $d = new Date::Business(FORCE => 'next'); # Monday (usually)

  $d->image(); # returns YYYYMMDD string
  $d->value(); # returns Unix time as integer

  $d->day_of_week();     # 0 = Sunday

  $d->datecmp($x);       # are two dates equal?
  $d->eq($x);            # synonym for datecmp
  $d->lt($x);            # less than
  $d->gt($x);            # greater than

  Calendar date functions
  $d->next();         # next calendar day
  $d->prev();         # previous calendar day
  $d->add(<offset>);  # adds n calendar days
  $d->sub(<offset>);  # subtracts n calendar days
  $d->diff($x);       # difference between two dates  
    
  Business date functions
  $d->nextb();        # next business day
  $d->prevb();        # previous business day
  $d->addb(<offset>); # adds n business days
  $d->subb(<offset>); # subtracts n business days
  $d->diffb($x);      # difference between two business dates  
  $d->diffb($x, 'next'); # treats $d weekend/holiday as next business date
  $d->diffb($x, 'next', 'next'); # treats $x weekend/holiday as above

DESCRIPTION

Business dates are weekdays only. Adding 1 to a weekend returns Monday, subtracting 1 returns Friday.

The difference in business days between Friday and the following Monday (using the diffb function) is one business day. The number of business days between Friday and the following Monday (using the betweenb function) is zero.

EXAMPLE

 $end   = new Date::Business(); # today
 # 10 business days ago
 $start = new Date::Business(DATE => $end, OFFSET => -10); 

 while (!$start->gt($end)) {
   compute_something($start);
   $start->nextb();
 }

HOLIDAYS

Sample holiday function:

 # MUST BE NON-WEEKEND HOLIDAYS !!!
 sub holiday($$) {
    my($start, $end) = @_;
    
    my($numHolidays) = 0;
    my($holiday, @holidays);
    
    push @holidays, '19981225'; # Christmas
    push @holidays, '19990101'; $ New Year's
    
    foreach $holiday (@holidays) {
        $numHolidays++ if ($start le $holiday && $end ge $holiday);
    }
    return $numHolidays;
 }

Example using the holiday function:

 # 10 business days after 21 DEC 1998, where
 # 25 DEC 1998 and 01 JAN 1999 are holidays
 #
 $d = new Date::Business(DATE    => '19981221',
                         OFFSET  => 10,
                         HOLIDAY => \&holiday);

 print $d->image."\n"; # prints 19990106

The diffb() function explained

The first parameter to the diffb function is the other date. The second parameter indicates that 'self' is to be treated as the previous or next business date if it is not a business date. The third parameter is similar to the second parameter but applies to the 'other' date. The default behavior is treat both dates as if the 'prev' option was set.

For example:

 $d = new Date::Business(DATE => '19991225'); # saturday
 $x = new Date::Business(DATE => '19991225'); # saturday
 print $d->image;                     # prints 19991225
 print $d->diffb($x);                 # prints  0
 print $d->diffb($x, 'prev', 'next'); # prints -1
 print $d->diffb($x, 'next', 'prev'); # prints  1
 print $d->diffb($x, 'next', 'next'); # prints  0

CAVEATS

Computations on dates that exceed the maximum value will wrap around. (i.e. the day after '20380119' is '19011214'). Computations that exceed the minimum value will result in the minimum value. (i.e. the day before '19011213' is '19011213')