view release on metacpan or  search on metacpan

lib/Date/Cmp.pm  view on Meta::CPAN

=head1 SYNOPSIS

  use Date::Cmp qw(datecmp);

  my $cmp = datecmp('1914', '1918');            # -1 (1914 is earlier)
  my $cmp = datecmp('Abt. 1850', '1855');       # -1
  my $cmp = datecmp('BET 1830 AND 1832', '1831'); # 0 (within range)

  # Optional complaint callback for ambiguous range edge-cases:
  $cmp = datecmp('1996-2000', '1996',
      sub { warn "ambiguous: @_" });

=head1 DESCRIPTION

C<Date::Cmp> provides a single exported function, C<datecmp>, which compares
two date strings or date-like objects, returning a numeric result like Perl's
C<< <=> >> operator.

The comparison handles approximate dates (C<Abt. 1902>, C<BET 1830 AND 1832>,
C<Oct/Nov/Dec 1950>), partial dates (year-only), and the common genealogy
qualifiers C<BEF> and C<AFT>.  Exact parsing delegates to
L<DateTime::Format::Genealogy>; a cascade of fast-path heuristics handles
the most common year-only comparisons without invoking the heavier parser.

=head1 FUNCTIONS

=head2 datecmp

=head3 Purpose

Compare two genealogy-style date strings (or date-like objects) and return
a value equivalent to Perl's spaceship operator (C<< <=> >>): C<-1> if the
left operand is earlier, C<0> if equivalent, or C<1> if later.

=head3 Arguments

=over 4

=item C<$left> (required)

The left-hand date.  Accepted types:

=over 8

=item * A string in any format listed under L</SUPPORTED FORMATS>.

=item * A blessed object with a C<date()> method returning a date string.

=item * A hash reference with a C<date> key whose value is a date string.

=back

=item C<$right> (required)

The right-hand date.  Accepts the same types as C<$left>.

=item C<$complain> (optional)

A CODE reference invoked with a diagnostic string for ambiguous conditions:
equal range endpoints or an inverted range.  C<undef> and other falsy values
are silently ignored (the guard is never triggered).  A truthy non-CODE
value causes an immediate C<croak>.

=back

=head3 Returns

=over 4

=item * C<-1> — C<$left> is earlier than C<$right>

=item * C<0>  — the two dates are considered equivalent

=item * C<1>  — C<$left> is later than C<$right>

=back

When either argument is C<undef> (or resolves to C<undef> after unwrapping),
the function prints a diagnostic to STDERR and returns C<0> rather than dying.
On a fatal parse failure it dies; the exception string begins with
C<"Date parse failure: ">.

=head3 Side Effects

May print coloured diagnostics to STDERR when dates cannot be parsed, when a
range is inverted, or when an argument is undefined.  The C<$complain>
callback is invoked (instead of STDERR output) for selected ambiguous
conditions.

=head3 EXAMPLE

  use Date::Cmp qw(datecmp);

  # Plain years
  datecmp('1900', '1950');              # -1

  # Approximate prefixes are stripped
  datecmp('Abt. 1850', '1850');        # 0
  datecmp('ca. 1799',  '1800');        # -1

  # Year ranges — any year within the range is "equal"
  datecmp('1 Jan 1831', '1830-1832');  # 0
  datecmp('BET 1830 AND 1832', '1829'); # 1  (range is later)

  # Blessed object with date() method
  package MyDate;
  sub new  { bless { d => $_[1] }, $_[0] }
  sub date { $_[0]->{d} }
  package main;
  datecmp(MyDate->new('1900'), '1950'); # -1

  # Hash ref with 'date' key
  datecmp({ date => '1900' }, '1950'); # -1

  # Sort a list of dates
  my @sorted = sort { datecmp($a, $b) } qw(1832 Abt. 1800 1756 BET 1815 AND 1820);

=head3 API SPECIFICATION

=head4 Input