NAME

Date::Cmp - Compare two dates with approximate parsing support

VERSION

Version 0.01

SYNOPSIS

use Date::Cmp qw(datecmp);

my $date1 = '1914';
my $date2 = '1918';
my $cmp = datecmp($date1, $date2);

# Optionally provide a complaint callback:
$cmp = datecmp($date1, $date2, sub { warn @_ });

DESCRIPTION

This module provides a single function, datecmp, which compares two date strings or date-like objects, returning a numeric comparison similar to Perl's spaceship operator (<=>).

The comparison is tolerant of approximate dates (e.g. "Abt. 1902", "BET 1830 AND 1832", "Oct/Nov/Dec 1950"), partial dates (years only), and strings with common genealogy-style formats. It attempts to normalize and parse these into comparable values using DateTime::Format::Genealogy.

FUNCTIONS

datecmp

my $result = datecmp($left, $right);
my $result = datecmp($left, $right, \&complain);

Compares two date strings or date-like objects and returns:

• -1 if $left is earlier than $right
• 0 if they are equivalent
• 1 if $left is later than $right

Parameters:

• $left, $right

  The values to compare. These may be strings in a variety of genealogical or ISO-style formats, or blessed objects that implement a date() method returning a date string.

• $complain (optional)

  A coderef that will be called with diagnostic messages when ambiguous or unexpected conditions are encountered, e.g. when comparing a range with equal endpoints.

SUPPORTED FORMATS

The function supports a variety of partial or approximate formats including:

• Exact dates (e.g. 1941-08-02, 5/27/1872)
• Years only (e.g. 1828)
• Approximate dates (e.g. Abt. 1802, ca. 1802, 1802 ?)
• Date ranges (e.g. 1802-1803, BET 1830 AND 1832)
• Month ranges (e.g. Oct/Nov/Dec 1950)
• Qualifiers like BEF, AFT

ERROR HANDLING

In cases where a date cannot be parsed or compared meaningfully, diagnostic messages will be printed to STDERR, and the function may die with an error. Callbacks and stack traces are used to help identify parsing issues.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

SEE ALSO

Sort::Key::DateTime

SUPPORT

This module is provided as-is without any warranty.

LICENCE AND COPYRIGHT

Copyright 2025 Nigel Horne.

Usage is subject to licence terms.

The licence terms of this software are as follows:

• Personal single user, single computer use: GPL2
• All other users (including Commercial, Charity, Educational, Government) must apply in writing for a licence for use from Nigel Horne at the above e-mail.