cpan/Time-Piece/Seconds.pm

   1 # $Id: Seconds.pm 44 2002-09-08 20:51:38Z matt $
   2
   3 package Time::Seconds;
   4 use strict;
   5 use vars qw/@EXPORT @EXPORT_OK @ISA/;
   6 # use UNIVERSAL qw(isa); # Commented out for Perl 5.12.0 by JRV to avoid a deprecation warning.
   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