Move Time::HiRes from ext/ to cpan/
[perl.git] / ext / 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);
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