| 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 | ||