blib/lib/Date/Tiny/Math.pm

filter: Statementstmt 100% 11 / 11 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 100% 15 / 15 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary
1 package Date::Tiny::Math;
2
3 1 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6
7 1 ▶use parent 'Date::Tiny';
Subroutine BEGIN: called CC=1 SCAR=0.0
8
9 use Carp;
10 use POSIX qw(floor);
11 use Scalar::Util qw(looks_like_number);
12
13 use overload
14 '+' => \&plus,
15 '-' => \&minus,
16 '<=>' => \&numcmp,
17 ;
18
19 our $VERSION = '1.00';
20
21 =encoding utf8
22
23 =head1 NAME
24
25 Date::Tiny::Math - A date object with maths, with as little code as
26 possible
27
28 =head1 SYNOPSIS
29
30 use Date::Tiny::Math;
31
32 # How many days have elapsed since 1 January 2000?
33 $date = Date::Tiny::Math->new(year => 2000, month => 1, day => 1);
34 $date2 = Date::Tiny::Math->new; # today
35 $elapsed_days = $date2 - $date;
36
37 $date3 = $date2 + 100; # 100 days after today
38 $date2 -= 7; # shift back by 7 days
39 ++$date2; # increment by 1 day
40
41 print "earlier\n" if $date2 < $date3;
42
43 =head1 DESCRIPTION
44
45 Date::Tiny::Math is a subclass of L<Date::Tiny> and adds the ability
46 to do simple arithmetic with the dates, assuming those dates to be
47 specified in the common, Gregorian, calendar -- even for dates
48 preceding the introduction of the Gregorian calendar in the year 1582.
49
50 =head1 METHODS
51
52 The below list of methods is in addition to the methods provided by
53 L<Date::Tiny>.
54
55 =cut
56
57 =head2 new
58
59 $date = Date::Tiny::Math->new(year => 2000, month => 1, day => 1);
60 $date = Date::Tiny::Math->new(cjdn => 2451545);
61
62 Creates a new instance based on the specified calendar date (year,
63 month, day) or Chronological Julian Day Number (CJDN). The CJDN is a
64 count of days since 24 November −4713 (Gregorian). It can be
65 positive, zero, or negative.
66
67 The Chronological Julian Day Number is distinct from the better known
68 integer Julian Day Number (JDN) and fractional Julian Day (JD) in that
69 the days don't begin at noon UTC but correspond to calendar days at
70 the location of interest.
71
72 =cut
73
74 sub new {
75 my ($class, %options) = @_;
76 my $self;
77 if (exists $options{cjdn}) {
78 croak "Cannot specify both a calendar date and the CJDN"
79 if exists $options{year}
80 or exists $options{month}
81 or exists $options{day};
82 $self = bless Date::Tiny->new, $class;
83 return $self->_set_cjdn($options{cjdn});
84 } else {
85 return bless Date::Tiny->new(%options), $class;
86 }
87 }
88
89 =head2 cjdn
90
91 $cjdn = $date->cjdn; # returns 2451545 for 2000-01-01
92
93 Returns the Chronological Julian Day Number (CJDN) for the specified
94 date object. The CJDN is the integer day count since 24 November
95 −4713 (Gregorian). It can be positive, zero, or negative.
96
97 =cut
98
99 sub cjdn {
100 my ($self) = @_;
101 unless (exists $self->{cjdn}) {
102 # based on https://aa.quae.nl/en/reken/juliaansedag.html
103 my ($alpha1, $m1) = idiv($self->{month} - 3, 12);
104 my $a1 = $self->{year} + $alpha1;
105 my ($c1, $a2) = idiv($a1, 100);
106 my $d1 = idiv(153*$m1 - 3, 5) + $self->{day};
107 my $d2 = idiv(36525*$a2, 100) + $d1;
108 $self->{cjdn} = idiv(146097*$c1, 4) + $d2 + 1721120;
109 }
110 return $self->{cjdn};
111 }
112
113 =head2 +, ++, +=
114
115 $date2 = $date1 + 17; # get the date 17 days later
116 $date2 = 17 + $date1; # same as previous
117 $date1 += 17; # modifies $date1
118 ++$date1; # adds 1 day to $date1
119
120 Adds a number to a date. The number is rounded down to the nearest
121 integer if needed.
122
123 Croaks if the non-date argument is not numerical.
124
125 =cut
126
127 sub plus {
128 my ($self, $other, $swap) = @_;
129 croak 'Cannot add a ' . ref($other) . " to a Date::Tiny::Math\n"
130 if ref $other;
131 croak "Cannot add a non-numerical scalar to a Date::Tiny::Math\n"
132 unless looks_like_number($other);
133 # create a clone of $self
134 my $result = bless { %{$self} }, ref($self);
135 $result->_set_cjdn($self->cjdn + $other);
136 return $result;
137 }
138
139 =head2 -, --, -+
140
141 $date2 = $date1 - 17; # get the date 17 days earlier
142 $date1 -= 17; # modifies $date1
143 $offset_in_days = $date2 - $date1; # difference between two dates
144 --$date1; # subtracts 1 day from $date1
145
146 # these croak:
147
148 $date2 = 17 - $date1; # cannot subtract a date from a number
149 $date2 -= $date1; # cannot modify LHS from date to scalar
150
151 Subtracts a number or a date from a date. The number is rounded down
152 to the nearest integer as needed.
153
154 If both arguments are dates then their difference measured in days is
155 returned.
156
157 Croaks if the non-date argument is not numerical, or if the left-hand
158 side isn't a L<Date::Tiny::Math>.
159
160 =cut
161
162 sub minus {
163 my ($self, $other, $swap) = @_;
164 # $self is always a Date::Tiny::Math;
165 if (ref $other) {
166 if ($other->isa('Date::Tiny')) { # want difference in days
167 # $other may not be a Date::Tiny::Math
168 $other = bless { %{$other} }, ref($self)
169 unless $other->isa('Date::Tiny::Math');
170 my $d = $other->cjdn - $self->cjdn;
171 return $swap? $d: -$d;
172 }
173 croak 'Cannot subtract a ' . ref($other) . " from a Date::Tiny::Math\n"
174 if $swap;
175 croak 'Cannot subtract a Date::Tiny::Math from a ' . ref($other) . "\n";
176 }
177 croak "Cannot subtract a Date::Tiny::Math from a non-Date::Tiny::Math\n"
178 if $swap;
179 croak "Cannot subtract a non-numerical scalar from a Date::Tiny::Math\n"
180 unless looks_like_number($other);
181 # otherwise want shifted date
182 # create a clone of $self
183 my $result = bless { %{$self} }, ref($self);
184 $result->_set_cjdn($self->cjdn - $other);
185 return $result;
186 }
187
188 =head2 numerical comparison
189
190 $date2 == $date3; # also < <= != <=> => >
191
192 Instances of L<Date::Tiny::Math> have the same order as their CJDN
193 values. Later dates compare as greater than earlier dates.
194
195 Croaks if not both arguments are instances of L<Date::Tiny::Math>.
196
197 NOTE: L<Date::Tiny>, the parent of the current module, does not
198 provide numerical comparison. It provides stringwise equality (C<eq>)
199 and not-equality (C<ne>) operators instead, which compare the
200 stringified versions of the dates. The current module inherits those
201 stringwise operators. It does not expand stringwise comparison by
202 implementing the inequality operators (C<lt>, C<le>, C<ge>, C<gt>)
203 because stringwise comparison does not define the same order as
204 numerical comparison when negative year numbers are involved.
205
206 =cut
207
208 sub numcmp {
209 my ($self, $other, $swap) = @_;
210 croak "Cannot compare a Date::Tiny::Math to a non-Date::Tiny::Math\n"
211 unless ref($other) and $other->isa('Date::Tiny::Math');
212 my $d = $other->cjdn - $self->cjdn;
213 return $swap? $d: -$d;
214 }
215
216 # internal methods and subroutines, not exposed:
217
218 # Integer division of $n by $d. Calculates $q and $r such that $n =
219 # $q*$d + $r and 0 < $r ≤ abs($d). Returns ($q, $r) in list context,
220 # or $q in scalar context.
221 sub idiv {
222 my ($n, $d) = @_;
223 use integer;
224 return undef unless $d; # prevent division by zero
225 my $q = $n/$d;
226 # rounding is likely toward zero, which means the remainder may be
227 # negative but we want it to always be nonnegative
228 my $r = $n%$d;
229 if ($r < 0) {
230 --$q;
231 $r += abs($d);
232 }
233 return wantarray? ($q, $r): $q;
234 }
235
236 # Sets the date object according to a CJDN. $cjdn is rounded down to
237 # the nearest integer. Returns the object.
238 sub _set_cjdn {
239 my ($self, $cjdn) = @_;
240 $cjdn = floor($cjdn);
241 if (not(defined $self->{cjdn}) or $self->{cjdn} != $cjdn) {
242 use integer;
243 $self->{cjdn} = $cjdn;
244 my $s = $cjdn - 1721120;
245 my ($c1, $omega3) = idiv(4*$s + 3, 146097);
246 my $d2 = idiv($omega3, 4);
247 my ($a2, $omega4) = idiv(100*$d2 + 99, 36525);
248 my $d1 = idiv($omega4, 100);
249 my ($m1, $omega5) = idiv(5*$d1 + 2, 153);
250 my $d0 = idiv($omega5, 5);
251 my ($alpha1, $m0) = idiv($m1 + 2, 12);
252 my $a1 = 100*$c1 + $a2;
253 $self->{year} = $a1 + $alpha1;
254 $self->{month} = $m0 + 1;
255 $self->{day} = $d0 + 1;
256 }
257 $self;
258 }
259
260 =head1 AUTHOR
261
262 Louis Strous, C<< <lstrous at cpan.org> >>
263
264 =head1 BUGS
265
266 Please report any bugs or feature requests to C<bug-date-tiny-math at
267 rt.cpan.org>, or through the web interface at
268 L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Tiny-Math>. I
269 will be notified, and then you'll automatically be notified of
270 progress on your bug as I make changes.
271
272 =head1 SUPPORT
273
274 You can find documentation for this module with the perldoc command.
275
276 perldoc Date::Tiny::Math
277
278 You can also look for information at:
279
280 =over 4
281
282 =item * RT: CPAN's request tracker (report bugs here)
283
284 L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Tiny-Math>
285
286 =item * CPAN Ratings
287
288 L<https://cpanratings.perl.org/d/Date-Tiny-Math>
289
290 =item * Search CPAN
291
292 L<https://metacpan.org/release/Date-Tiny-Math>
293
294 =back
295
296 =head1 LICENSE AND COPYRIGHT
297
298 This software is Copyright (c) 2025 by Louis Strous.
299
300 This is free software, licensed under:
301
302 The Artistic License 2.0 (GPL Compatible)
303
304 =cut
305
306 1; # End of Date::Tiny::Math
↑ Summary