NAME

Time::Available - Perl extension to calculate time availability

SYNOPSIS

  use Time::Available;

  # init interval and dayMask
  my $interval = new( start=>'07:00', stop=>'17:00',
        dayMask=> Time::Available::DAY_WEEKDAY );

  # alternative way to init module using exporting of days
  use Time::Available qw(:days);
  my $interval = new( start=>'07:00', stop=>'17:00',
        dayMask=> DAY_WEEKDAY );

  # calculate current uptime availability from now in seconds
  print $interval->uptime(localtime);

  # calculate maximum downtime in seconds from current moment
  print $interval->downtime(localtime);

  # calculate availablity in seconds from interval of uptime
  print $interval->interval($utime1,$utime2);

  # pretty print interval data (this will produce output '1d 11:11:11')
  use Time::Available qw(:fmt_interval);
  print fmt_interval(126671);

DESCRIPTION

Time::Available is used to calculate availability of some resource if start and end time of availability is supplied. Availability is calculated relative to some interval which is defined when new instance of module is created.

Start and end dates must be specified in 24-hour format. You can specify just hour, hour:minute or hour:minute:seconds format. Start and end time is specified in your local time zone. Timestamp, are specified in unix utime, and module will take care of recalculating (using localtime and timelocal when needed). There is one small canvat here: module is assuing that time you are specifing is in same time zone in which your module is running (that is from local system).

The dayMask parameter is constructed by OR'ing together one or more of the following dayMask constants:

• Time::Available::DAY_MONDAY

• Time::Available::DAY_TUESDAY

• Time::Available::DAY_WEDNESDAY

• Time::Available::DAY_THURSDAY

• Time::Available::DAY_FRIDAY

• Time::Available::DAY_SATURDAY

• Time::Available::DAY_SUNDAY

• Time::Available::DAY_WEEKDAY

• Time::Available::DAY_WEEKEND

• Time::Available::DAY_EVERYDAY

They should be self-explainatory.

EXPORT

None by default.

If you specify :days, Time::Available will export all DAY_* constraints to your enviroment (causing possible pollution of name space). You have been warned.

With :fmt_interval it will include function fmt_interval which will pretty-format interval into [days]d hh:mm:ss.

HISTORY

0.01

Original version; based somewhat on Time::Avail code

0.02

First version which works well

0.03

Fix intervals which start with 0 hours, and bug with sunday (it never matched dayMask)

0.04

Fixed bug when interval begins in previous day and end before start of interval

0.05

Fixed another bug when interval begins in non-masked day and ends after begining of interval

BUGS

• Allow arbitary (array?) of holidays to be included.

SEE ALSO

Time::Avail is CPAN module that started it all. However, it lacked calculating of availability of some interval and precision in seconds, so this module was born. It also had some bugs in dayMask which where reported to author, but his e-mail address bounced.

More information about this module might be found on http://www.rot13.org/~dpavlin/projects.html#cpan

AUTHOR

Dobrica Pavlinusic, <dpavlin@rot13.org>

COPYRIGHT AND LICENSE

Copyright (C) 2003-2006 by Dobrica Pavlinusic

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.