blib/lib/Date/Age.pm

filter: Statementstmt 97.3% 74 / 76 Branchbran 82.3% 28 / 34 Conditioncond 50.0% 6 / 12 MC/DCmcdc 25.0% 2 / 8 Subroutinesub 100% 14 / 14 Podpod 100% 2 / 2 totaltotal 86.3% 126 / 146 CC 22 SCAR 14.5
CC
22
Cov
89%
details
6.4
_validate_ymd_strict
6.1
_parse_date_range
6.1
CRAP 4.3
↑ Summary
1 package Date::Age;
2  
3 3 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 3 ▶use Carp qw(carp croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
10 3 ▶use Time::Local qw(timelocal);
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 3 our @EXPORT_OK = qw(describe details);
13  
14 =head1 NAME
15  
16 Date::Age - Return an age or age range from date(s)
17  
18 =head1 VERSION
19  
20 Version 0.07
21  
22 =cut
23  
24 3 our $VERSION = '0.07';
25  
26 =head1 SYNOPSIS
27  
28 use Date::Age qw(describe details);
29  
30 print describe('1943', '2016-01-01'), "\n"; # '72-73'
31  
32 my $data = details('1943-05-01', '2016-01-01');
33 # { min_age => 72, max_age => 72, range => '72', precise => 72 }
34  
35 =head1 DESCRIPTION
36  
37 This module calculates the age or possible age range between a date of birth
38 and another date (typically now or a death date).
39 It works even with partial dates.
40  
41 =head1 METHODS
42  
43 =head1 FUNCTIONS
44  
45 =head2 describe
46  
47 my $range = describe($dob);
48 my $range = describe($dob, $ref_date);
49  
50 Returns a human-readable age or age range for the supplied date of birth.
51  
52 C<describe()> accepts a date of birth in any of the formats supported by
53 L</details> (year only, year-month, or full year-month-day). An optional
54 reference date may also be provided; if omitted, the current local date is
55 used.
56  
57 Because partial dates imply uncertainty, the routine may return either a
58 single age (e.g. C<"72">) or an age range (e.g. C<"72-73">). Year-only and
59 year-month dates can span a range of possible birthdays, and therefore a
60 range of possible ages.
61  
62 Examples:
63  
64 describe('1943'); # e.g. '80-81'
65 describe('1943-05', '2016'); # '72-73'
66 describe('1943-05-01', '2016-01-01'); # '72'
67  
68 This routine is a convenience wrapper around C<details()> that returns only
69 the formatted range string.
70  
71 =cut
72  
73 4 ▶sub describe {
Subroutine describe: called CC=3 SCAR=11.8
Pod documented
74 4 ▶ if($_[0] eq __PACKAGE__) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] eq __PACKAGE__) 0 4 4
75 0 shift;
76 }
77  
78 4 ▶ croak('Usage: ', __PACKAGE__, '::describe($dob, $ref)') if(scalar(@_) == 0);
Branch: 1 branch
BranchTrueFalseTotal
if scalar @_ == 0 0 4 4
79  
80 4 my ($dob, $ref) = @_;
81 4 my $info = details($dob, $ref);
82 3 return $info->{range};
83 }
84  
85 =head2 details
86  
87 my $info = details($dob);
88 my $info = details($dob, $ref_date);
89  
90 Returns a hashref describing the full computed age information. This routine
91 performs the underlying date-range expansion and age calculation that
92 C<describe()> relies on.
93  
94 The returned hashref contains:
95  
96 =over 4
97  
98 =item * C<min_age>
99  
100 The minimum possible age based on the earliest possible birthday within the
101 supplied date specification.
102  
103 =item * C<max_age>
104  
105 The maximum possible age based on the latest possible birthday.
106  
107 =item * C<range>
108  
109 A string representation of the age or age range, such as C<"72"> or
110 C<"72-73">.
111  
112 =item * C<precise>
113  
114 If the age is unambiguous (e.g. the date of birth and reference date are both
115 fully specified), this is the exact age as an integer. Otherwise it is
116 C<undef>.
117  
118 =back
119  
120 Supported date formats for both C<$dob> and C<$ref_date> are:
121  
122 =over 4
123  
124 =item * C<YYYY> - year only (e.g. C<1943>)
125  
126 =item * C<YYYY-MM> - year and month (e.g. C<1943-05>)
127  
128 =item * C<YYYY-MM-DD> - full date (e.g. C<1943-05-01>)
129  
130 =back
131  
132 Invalid or unrecognised date strings will cause the routine to C<croak()>.
133  
134 Example:
135  
136 my $info = details('1943-05-01', '2016-01-01');
137  
138 # {
139 # min_age => 72,
140 # max_age => 72,
141 # range => '72',
142 # precise => 72,
143 # }
144  
145 When the reference date is omitted, the current local date (YYYY-MM-DD) is
146 used.
147  
148 =cut
149  
150 13 ▶sub details {
Subroutine details: called CC=6 SCAR=18.6
Pod documented
151 13 ▶ if($_[0] eq __PACKAGE__) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] eq __PACKAGE__) 0 13 13
152 0 shift;
153 }
154  
155 13 ▶ croak('Usage: ', __PACKAGE__, '::details($dob, $ref)') if(scalar(@_) == 0);
Branch: 1 branch
BranchTrueFalseTotal
if scalar @_ == 0 0 13 13
156  
157 13 my ($dob, $ref) = @_;
158  
159 13 my ($dob_early, $dob_late) = _parse_date_range($dob);
160 8 ▶ my ($ref_early, $ref_late) = _parse_date_range($ref // _now_string());
Condition33%1/3
$ref // _now_string()
l!l&&r!l&&!r
800
MC/DC0%0/2
$ref // _now_string()
$ref _now_string()
Truth table33%1/3
A // B
A= $refB= _now_string()
ABresult
1X1
011
000
161  
162 8 my $min_age = _calc_age_localtime($dob_late, $ref_early);
163 8 my $max_age = _calc_age_localtime($dob_early, $ref_late);
164  
165 8 ▶ my $range_str = $min_age == $max_age ? $min_age : "$min_age-$max_age";
Branch: 1 branch
BranchTrueFalseTotal
$min_age == $max_age ? : 6 2 8
166 8 ▶ my $precise = ($min_age == $max_age) ? $min_age : undef;
Branch: 1 branch
BranchTrueFalseTotal
$min_age == $max_age ? : 6 2 8
167  
168 return {
169 8 min_age => $min_age,
170 max_age => $max_age,
171 range => $range_str,
172 precise => $precise,
173 };
174 }
175  
176 1 ▶sub _now_string {
Subroutine _now_string: called CC=1 SCAR=0.0
177 1 my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime();
178 1 return sprintf('%04d-%02d-%02d', $year + 1900, $mon + 1, $mday);
179 }
180  
181 16 ▶sub _calc_age_localtime {
Subroutine _calc_age_localtime: called CC=2 SCAR=6.9
182 16 my ($dob, $ref) = @_; # both in YYYY-MM-DD format
183  
184 # Parse manually
185 16 my ($dy, $dm, $dd) = split /-/, $dob;
186 16 my ($ry, $rm, $rd) = split /-/, $ref;
187  
188 # Convert to epoch for comparison
189 # Note: months are 0-11 for timelocal
190 16 my $dob_epoch = timelocal(0, 0, 0, $dd, $dm - 1, $dy);
191 16 my $ref_epoch = timelocal(0, 0, 0, $rd, $rm - 1, $ry);
192  
193 16 my $age = $ry - $dy;
194  
195 # Check if birthday has occurred this year
196 16 ▶ if ($ref_epoch < timelocal(0, 0, 0, $dd, $dm - 1, $ry)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ref_epoch < timelocal(0, 0, 0, $dd, $dm - 1, $ry)) 8 8 16
197 8 $age--;
198 }
199  
200 16 return $age;
201 }
202  
203 21 ▶sub _parse_date_range {
Subroutine _parse_date_range: called CC=6 SCAR=18.0
204 21 my $date = shift;
205  
206 21 ▶ if ($date =~ /^\d{4}-\d{2}-\d{2}$/) {
Branch: 3 branches
BranchTrueFalseTotal
if ($date =~ /^\d{4}-\d{2}-\d{2}$/) { } 16 5 21
elsif ($date =~ /^(\d{4})-(\d{2})$/) { } 2 3 5
elsif ($date =~ /^(\d{4})$/) { } 2 1 3
207 16 _validate_ymd_strict($date);
208 12 return ($date, $date);
209 } elsif ($date =~ /^(\d{4})-(\d{2})$/) {
210 2 my ($y, $m) = ($1, $2);
211 2 ▶ die "Invalid month in date '$date'" if $m < 1 || $m > 12;
Branch: 1 branch
BranchTrueFalseTotal
if $m < 1 or $m > 12 0 2 2
Condition33%1/3
$m < 1 or $m > 12
l!l&&r!l&&!r
002
MC/DC0%0/2
$m < 1 or $m > 12
$m < 1 $m > 12
Truth table33%1/3
A or B
A= $m < 1B= $m > 12
ABresult
1X1
011
000
212  
213 2 my $start = "$y-$m-01";
214 2 my $end = _end_of_month($y, $m);
215  
216 2 _validate_ymd_strict($start);
217 2 _validate_ymd_strict($end);
218  
219 2 return ($start, $end);
220 } elsif ($date =~ /^(\d{4})$/) {
221 2 return ("$1-01-01", "$1-12-31");
222 } else {
223 1 die "Unrecognized date format: $date";
224 }
225 }
226  
227 20 ▶sub _validate_ymd_strict {
Subroutine _validate_ymd_strict: called CC=6 SCAR=18.2
228 20 my $date = $_[0];
229  
230 # YYYY-MM-DD only
231 20 ▶ return unless $date =~ /^(\d{4})-(\d{2})-(\d{2})$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $date =~ /^(\d{4})-(\d{2})-(\d{2})$/ 0 20 20
232 20 my ($y, $m, $d) = ($1, $2, $3);
233  
234 20 ▶ die "Invalid month in date '$date'" if $m < 1 || $m > 12;
Branch: 1 branch
BranchTrueFalseTotal
if $m < 1 or $m > 12 2 18 20
Condition66%2/3
$m < 1 or $m > 12
l!l&&r!l&&!r
0218
MC/DC50%1/2
$m < 1 or $m > 12
$m < 1 $m > 12
Truth table66%2/3
A or B
A= $m < 1B= $m > 12
ABresult
1X1
011
000
235  
236 18 my @dim = (31, 28 + _is_leap($y), 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
237 18 my $max_d = $dim[$m - 1];
238  
239 18 ▶ die "Invalid day in date '$date'" if $d < 1 || $d > $max_d;
Branch: 1 branch
BranchTrueFalseTotal
if $d < 1 or $d > $max_d 2 16 18
Condition66%2/3
$d < 1 or $d > $max_d
l!l&&r!l&&!r
0216
MC/DC50%1/2
$d < 1 or $d > $max_d
$d < 1 $d > $max_d
Truth table66%2/3
A or B
A= $d < 1B= $d > $max_d
ABresult
1X1
011
000
240 }
241  
242 5 ▶sub _end_of_month {
Subroutine _end_of_month: called CC=1 SCAR=0.0
243 5 my ($y, $m) = @_;
244  
245 5 my @days_in_month = (31, 28 + _is_leap($y), 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
246 5 return sprintf('%04d-%02d-%02d', $y, $m, $days_in_month[$m - 1]);
247 }
248  
249 27 ▶sub _is_leap {
Subroutine _is_leap: called CC=4 SCAR=13.9
250 27 my $y = $_[0];
251  
252 27 ▶ return 1 if $y % 400 == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $y % 400 == 0 14 13 27
253 13 ▶ return 0 if $y % 100 == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $y % 100 == 0 1 12 13
254 12 ▶ return 1 if $y % 4 == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $y % 4 == 0 8 4 12
255 4 return 0;
256 }
257  
258 3 1;
259  
260 __END__
↑ Summary