NAME

DateTime::Calendar::Christian - Dates in the Christian calendar

SYNOPSIS

use DateTime::Calendar::Christian;

$dt = DateTime::Calendar::Christian->new( year  => 1752,
                                          month => 10,
                                          day   => 4,
                                          reform_date => $datetime );

DESCRIPTION

DateTime::Calendar::Christian is the implementation of the combined Julian and Gregorian calendar.

See DateTime for information about most of the methods.

BACKGROUND

The Julian calendar, introduced in Roman times, had an average year length of 365.25 days, about 0.03 days more than the correct number. When this difference had cummulated to about ten days, the calendar was reformed by pope Gregory XIII, who introduced a new leap year rule. To correct for the error that had built up over the centuries, ten days were skipped in October 1582. In most countries, the change date was later than that; England went Gregorian in 1752, and Russia didn't change over until 1918.

METHODS

This manpage only describes those methods that differ from those of DateTime. See DateTime for all other methods.

• new( ... )

  Besides the usual parameters ("year", "month", "day", "hour", "minute", "second", "nanosecond", "fractional_seconds", "language" and "time_zone"), this class method takes the additional "reform_date" parameter. This parameter can be a DateTime object (or an object that can be converted into a DateTime). This denotes the first date of the Gregorian calendar. It can also be a string, containing the name of a location, e.g. 'Italy'.

  If this method is used as an instance method and no "reform_date" is given, the "reform_date" of the returned object is the same as the one of the object used to call this constructor. This means you can make "date generators", that implement a calendar with a fixed reform date:

  $english_calendar = DateTime::Calendar::Christian(
                          reform_date => DateTime->new( year  => 1752,
                                                        month => 9,
                                                        day   => 14 )
                                                   );

  or equivalently:

  $english_calendar = DateTime::Calendar::Christian(
                          reform_date => 'UK' );

  You can use this generator to create dates with the given reform_date:

  $born = $english_calendar->new( year => 1732, month => 2, day => 22 );
  $died = $english_calendar->new( year => 1799, month => 12, day => 14 );

  When a date is given that was skipped during a calendar reform, it is assumed that it is a Gregorian date, which is then converted to the corresponding Julian date. This behaviour may change in future versions. If a date is given that can be both Julian and Gregorian, it will be considered Julian. This is a bug.

• from_epoch

  This method accepts an additional "reform_date" argument. Note that the epoch is defined for most (all?) systems as a date in the Gregorian calendar.

• reform_date

  Returns the date of the calendar reform, as a DateTime object.

• is_julian, is_gregorian

  Return true or false indicating whether the datetime object is in a specific calendar.

• is_leap_year

  This method returns a true or false indicating whether or not the datetime object is in a leap year. If the object is in the year of the date reform, this method indicates whether there is a leap day in that year, irrespective of whether the datetime object is in the same calendar as the possible leap day.

• days_in_year

  Returns the number of days in the year. Is equal to 365 or 366, except for the year(s) of the calendar reform.

• gregorian_deviation( [$datetime] )

  This method returns the difference in days between the Gregorian and the Julian calendar. If the parameter $datetime is given, it will be used to calculate the result; in this case this method can be used as a class method.

BUGS

• There are problems with calendars switch to Gregorian before 200 AD or after about 4000 AD. Before 200 AD, this switch leads to duplication of dates. After about 4000 AD, there could be entire missing months. (The module can handle dates before 200 AD or after 4000 AD just fine; it's just the calendar reform dates that should be inside these limits.)

• There may be functions that give the wrong results for the year of the calendar reform. The function truncate is a known problem. If you find any more problems, please let me know.

SUPPORT

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

AUTHOR

Eugene van der Pijll <pijll@gmx.net>

COPYRIGHT

Copyright (c) 2003 Eugene van der Pijll. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

DateTime, DateTime::Calendar::Julian

datetime@perl.org mailing list