[Summary view] [Print] [Text view]

   1  # $Id: Seconds.pm 69 2006-09-07 17:41:05Z matt $
   2  
   3  package Time::Seconds;
   4  use strict;
   5  use vars qw/@EXPORT @EXPORT_OK @ISA/;
   6  use UNIVERSAL qw(isa);
   7  
   8  @ISA = 'Exporter';
   9  
  10  @EXPORT = qw(
  11          ONE_MINUTE 
  12          ONE_HOUR 
  13          ONE_DAY 
  14          ONE_WEEK 
  15          ONE_MONTH
  16                  ONE_REAL_MONTH
  17          ONE_YEAR
  18                  ONE_REAL_YEAR
  19          ONE_FINANCIAL_MONTH
  20          LEAP_YEAR 
  21          NON_LEAP_YEAR
  22          );
  23  
  24  @EXPORT_OK = qw(cs_sec cs_mon);
  25  
  26  use constant ONE_MINUTE => 60;
  27  use constant ONE_HOUR => 3_600;
  28  use constant ONE_DAY => 86_400;
  29  use constant ONE_WEEK => 604_800;
  30  use constant ONE_MONTH => 2_629_744; # ONE_YEAR / 12
  31  use constant ONE_REAL_MONTH => '1M';
  32  use constant ONE_YEAR => 31_556_930; # 365.24225 days
  33  use constant ONE_REAL_YEAR  => '1Y';
  34  use constant ONE_FINANCIAL_MONTH => 2_592_000; # 30 days
  35  use constant LEAP_YEAR => 31_622_400; # 366 * ONE_DAY
  36  use constant NON_LEAP_YEAR => 31_536_000; # 365 * ONE_DAY
  37  
  38  # hacks to make Time::Piece compile once again
  39  use constant cs_sec => 0;
  40  use constant cs_mon => 1;
  41  
  42  use overload 
  43                  'fallback' => 'undef',
  44          '0+' => \&seconds,
  45          '""' => \&seconds,
  46          '<=>' => \&compare,
  47          '+' => \&add,
  48                  '-' => \&subtract,
  49                  '-=' => \&subtract_from,
  50                  '+=' => \&add_to,
  51                  '=' => \&copy;
  52  
  53  sub new {
  54      my $class = shift;
  55      my ($val) = @_;
  56      $val = 0 unless defined $val;
  57      bless \$val, $class;
  58  }
  59  
  60  sub _get_ovlvals {
  61      my ($lhs, $rhs, $reverse) = @_;
  62      $lhs = $lhs->seconds;
  63  
  64      if (UNIVERSAL::isa($rhs, 'Time::Seconds')) {
  65          $rhs = $rhs->seconds;
  66      }
  67      elsif (ref($rhs)) {
  68          die "Can't use non Seconds object in operator overload";
  69      }
  70  
  71      if ($reverse) {
  72          return $rhs, $lhs;
  73      }
  74  
  75      return $lhs, $rhs;
  76  }
  77  
  78  sub compare {
  79      my ($lhs, $rhs) = _get_ovlvals(@_);
  80      return $lhs <=> $rhs;
  81  }
  82  
  83  sub add {
  84      my ($lhs, $rhs) = _get_ovlvals(@_);
  85      return Time::Seconds->new($lhs + $rhs);
  86  }
  87  
  88  sub add_to {
  89      my $lhs = shift;
  90      my $rhs = shift;
  91      $rhs = $rhs->seconds if UNIVERSAL::isa($rhs, 'Time::Seconds');
  92      $$lhs += $rhs;
  93      return $lhs;
  94  }
  95  
  96  sub subtract {
  97      my ($lhs, $rhs) = _get_ovlvals(@_);
  98      return Time::Seconds->new($lhs - $rhs);
  99  }
 100  
 101  sub subtract_from {
 102      my $lhs = shift;
 103      my $rhs = shift;
 104      $rhs = $rhs->seconds if UNIVERSAL::isa($rhs, 'Time::Seconds');
 105      $$lhs -= $rhs;
 106      return $lhs;
 107  }
 108  
 109  sub copy {
 110      Time::Seconds->new(${$_[0]});
 111  }
 112  
 113  sub seconds {
 114      my $s = shift;
 115      return $$s;
 116  }
 117  
 118  sub minutes {
 119      my $s = shift;
 120      return $$s / 60;
 121  }
 122  
 123  sub hours {
 124      my $s = shift;
 125      $s->minutes / 60;
 126  }
 127  
 128  sub days {
 129      my $s = shift;
 130      $s->hours / 24;
 131  }
 132  
 133  sub weeks {
 134      my $s = shift;
 135      $s->days / 7;
 136  }
 137  
 138  sub months {
 139      my $s = shift;
 140      $s->days / 30.4368541;
 141  }
 142  
 143  sub financial_months {
 144      my $s = shift;
 145      $s->days / 30;
 146  }
 147  
 148  sub years {
 149      my $s = shift;
 150      $s->days / 365.24225;
 151  }
 152  
 153  1;
 154  __END__
 155  
 156  =head1 NAME
 157  
 158  Time::Seconds - a simple API to convert seconds to other date values
 159  
 160  =head1 SYNOPSIS
 161  
 162      use Time::Piece;
 163      use Time::Seconds;
 164      
 165      my $t = localtime;
 166      $t += ONE_DAY;
 167      
 168      my $t2 = localtime;
 169      my $s = $t - $t2;
 170      
 171      print "Difference is: ", $s->days, "\n";
 172  
 173  =head1 DESCRIPTION
 174  
 175  This module is part of the Time::Piece distribution. It allows the user
 176  to find out the number of minutes, hours, days, weeks or years in a given
 177  number of seconds. It is returned by Time::Piece when you delta two
 178  Time::Piece objects.
 179  
 180  Time::Seconds also exports the following constants:
 181  
 182      ONE_DAY
 183      ONE_WEEK
 184      ONE_HOUR
 185      ONE_MINUTE
 186      ONE_MONTH
 187      ONE_YEAR
 188      ONE_FINANCIAL_MONTH
 189      LEAP_YEAR
 190      NON_LEAP_YEAR
 191  
 192  Since perl does not (yet?) support constant objects, these constants are in
 193  seconds only, so you cannot, for example, do this: C<print ONE_WEEK-E<gt>minutes;>
 194  
 195  =head1 METHODS
 196  
 197  The following methods are available:
 198  
 199      my $val = Time::Seconds->new(SECONDS)
 200      $val->seconds;
 201      $val->minutes;
 202      $val->hours;
 203      $val->days;
 204      $val->weeks;
 205      $val->months;
 206      $val->financial_months; # 30 days
 207      $val->years;
 208  
 209  The methods make the assumption that there are 24 hours in a day, 7 days in
 210  a week, 365.24225 days in a year and 12 months in a year.
 211  (from The Calendar FAQ at http://www.tondering.dk/claus/calendar.html)
 212  
 213  =head1 AUTHOR
 214  
 215  Matt Sergeant, matt@sergeant.org
 216  
 217  Tobias Brox, tobiasb@tobiasb.funcom.com
 218  
 219  Bal�zs Szab� (dLux), dlux@kapu.hu
 220  
 221  =head1 LICENSE
 222  
 223  Please see Time::Piece for the license.
 224  
 225  =head1 Bugs
 226  
 227  Currently the methods aren't as efficient as they could be, for reasons of
 228  clarity. This is probably a bad idea.
 229  
 230  =cut