File Coverage

=head1 NAME

Date::Age - Return an age or age range from date(s)

=head1 VERSION

Version 0.07

=cut

=head1 SYNOPSIS

  use Date::Age qw(describe details);

  print describe('1943', '2016-01-01'), "\n"; # '72-73'

  my $data = details('1943-05-01', '2016-01-01');
  # { min_age => 72, max_age => 72, range => '72', precise => 72 }

=head1 DESCRIPTION

This module calculates the age or possible age range between a date of birth
and another date (typically now or a death date).
It works even with partial dates.

=head1 METHODS

=head1 FUNCTIONS

=head2 describe($dob, $ref_date)

  my $range = describe($dob);
  my $range = describe($dob, $ref_date);

=over 4

=item $dob

Date of birth, in any format supported by C<details()>.

=item $ref_date

Optional reference date. If omitted, the current local date is used.

=back

Returns a string containing a human-readable age or age range for the supplied date of birth.

C<describe()> accepts a date of birth in any of the formats supported by
L</details> (year only, year-month, or full year-month-day).  An optional
reference date may also be provided; if omitted, the current local date is
used.

Because partial dates imply uncertainty, the routine may return either a
single age (e.g. C<"72">) or an age range (e.g. C<"72-73">).  Year-only and
year-month dates can span a range of possible birthdays, and therefore a
range of possible ages.

Examples:

  describe('1943');     # e.g. '80-81'
  describe('1943-05', '2016');  # '72-73'
  describe('1943-05-01', '2016-01-01');  # '72'

This routine is a convenience wrapper around C<details()> that returns only
the formatted range string.

=cut

=head2 details($dob, $ref_date)

  my $info = details($dob);
  my $info = details($dob, $ref_date);

=over 4

=item $dob

Date of birth, in any format supported by C<details()>.

=item $ref_date

Optional reference date. If omitted, the current local date is used.

=back

Returns a hashref describing the full computed age information.  This routine
performs the underlying date-range expansion and age calculation that
C<describe()> relies on.

The returned hashref contains:

=over 4

=item * C<min_age>

The minimum possible age based on the earliest possible birthday within the
supplied date specification.

=item * C<max_age>

The maximum possible age based on the latest possible birthday.

=item * C<range>

A string representation of the age or age range, such as C<"72"> or
C<"72-73">.

=item * C<precise>

If the age is unambiguous (e.g. the date of birth and reference date are both
fully specified), this is the exact age as an integer.  Otherwise it is
C<undef>.

=back

Supported date formats for both C<$dob> and C<$ref_date> are:

=over 4

=item * C<YYYY> - year only (e.g. C<1943>)

=item * C<YYYY-MM> - year and month (e.g. C<1943-05>)

=item * C<YYYY-MM-DD> - full date (e.g. C<1943-05-01>)

=back

Invalid or unrecognised date strings will cause the routine to C<croak()>.

Example:

  my $info = details('1943-05-01', '2016-01-01');

  # {
  #   min_age => 72,
  #   max_age => 72,
  #   range   => '72',
  #   precise => 72,
  # }

When the reference date is omitted, the current local date (YYYY-MM-DD) is
used.

=cut