NAME

Date::Gregorian - Gregorian calendar

SYNOPSIS

use Date::Gregorian;

$date = Date::Gregorian->new->set_ymd(1999, 12, 31);

if ($date->check_ymd($y, $m, $d)) {
  # valid, $date has new value
}
else {
  # not valid, $date keeps old value
}

($y, $m, $d) = $date->get_ymd;

$wd = (qw(Mon Tue Wed Thu Fri Sat Sun))[$date->get_weekday];
$date->set_yd(2000, 366);           # Dec 31, 2000
($y, $d) = $date->get_yd;
$date->set_ywd(1998, 53, 6);        # Sun Jan 3, 1999
($y, $w, $d) = $date->get_ywd;
$date->add_days($delta);
$delta = $date->get_days_since($otherdate);
$date->set_easter($y);
$date->set_gmtime($time);
$time = $date->get_gmtime;
$date->configure(1752, 9, 14);
$date->configure(1752, 9, 14, 1753);        # United Kingdom
$date->set_date($otherdate);        # change date, keep configuration
$date = $otherdate->new;            # copy date, propagate config.

if ($date->is_gregorian) {
  # date is past configured calendar reformation, thus in Gregorian notation
}
else {
  # date is before configured calendar reformation, thus in Julian notation
}

# get the first sunday in October:
$date->set_ymd($year, 10,  1)->set_weekday(6, '>=');
# get the last sunday in October:
$date->set_ymd($year, 11,  1)->set_weekday(6, '<');

DESCRIPTION

Calendars define some notation to identify days in history. The Gregorian calendar, now in wide use, was established by Pope Gregory XIII in AD 1582 as an improvement over the less accurate Julian calendar that had been in use before. Both of these calendars also determine certain holidays. Unfortunately, the new one was not adopted everywhere at the same time. Thus, the correct date for a given historic event can depend on its location. Astronomers usually expand the official Julian/Gregorian calendar backwards beyond AD 1 using zero and negative numbers, so that year 0 is 1 BC, year -1 is 2 BC, etc.

This module provides an object class representing days in history. You can get earlier or later dates by way of adding days to them, determine the difference in days between two of them, and read out the day, month and year number as the (astronomic) Gregorian calendar defines them (numbers 1 through 12 representing January through December). Moreover, you can find out weekdays, easter sundays, week in year and day in year numbers.

For convenience, it is also possible to define the switching day from Julian to Gregorian dates and the switching year from Julian to Gregorian easter schedule. Use configure with the first valid date of the new calendar and optionally the first year the new easter schedule was used (default 1583).

The module is based on an algorithm devised by C. F. Gauss (1777-1855). It is completely written in Perl for maximum portability.

All methods except get_* return their object. This allows for shortcuts like:

$pentecost = Date::Gregorian->new->set_easter(2000)->add_days(49);

The optional relation parameter for set_weekday may be one of '>=', '>', '<=', or '<'. Default is '>='. This method finds the nearest date that is "not earlier", later, "not later", or earlier, respectively, than the given date and matches the given weekday.

Numbers 0 through 6 represent weekdays Monday through Sunday. Day in month ranges from 1 to 31, day in year from 1 to 366, week in year from 1 to 53. Weeks are supposed to start on Monday. The first week of a year is the one containing January 4th. These definitions are slightly closer to ISO/R 2015-1971 than to Perl's builtin time conversion functions. Weekday numbers, however, are zero-based for Perl's sake, i.e. ease of use as array indices.

AUTHOR

Martin Hasch <martin@mathematik.uni-ulm.de>, November 1999.

CAVEATS

Does not work with non-integer values.

SEE ALSO

The sci.astro Calendar FAQ, Date::Calc, Date::Gregorian::Exact.