NAME

Calendar::China - Perl extension for Chinese calendar

SYNOPSIS

use Calendar;
my $date = Calendar->new_from_China(78, 22, 12, 2);

or construct from Gregorian:
my $date = Calendar->new_from_Gregorian(1, 1, 2006)->convert_to_China();

DESCRIPTION

From "FREQUENTLY ASKED QUESTIONS ABOUT CALENDARS"(http://www.tondering.dk/claus/calendar.html)

The Chinese calendar - like the Hebrew - is a combined solar/lunar calendar in that it strives to have its years coincide with the tropical year and its months coincide with the synodic months. It is not surprising that a few similarities exist between the Chinese and the Hebrew calendar:

* An ordinary year has 12 months, a leap year has 13 months.
* An ordinary year has 353, 354, or 355 days, a leap year has 383,
  384, or 385 days.

When determining what a Chinese year looks like, one must make a number of astronomical calculations:

First, determine the dates for the new moons. Here, a new moon is the completely "black" moon (that is, when the moon is in conjunction with the sun), not the first visible crescent used in the Islamic and Hebrew calendars. The date of a new moon is the first day of a new month.

Secondly, determine the dates when the sun's longitude is a multiple of 30 degrees. (The sun's longitude is 0 at Vernal Equinox, 90 at Summer Solstice, 180 at Autumnal Equinox, and 270 at Winter Solstice.) These dates are called the "Principal Terms" and are used to determine the number of each month:

Principal Term 1 occurs when the sun's longitude is 330 degrees. Principal Term 2 occurs when the sun's longitude is 0 degrees. Principal Term 3 occurs when the sun's longitude is 30 degrees. etc. Principal Term 11 occurs when the sun's longitude is 270 degrees. Principal Term 12 occurs when the sun's longitude is 300 degrees.

Each month carries the number of the Principal Term that occurs in that month.

In rare cases, a month may contain two Principal Terms; in this case the months numbers may have to be shifted. Principal Term 11 (Winter Solstice) must always fall in the 11th month.

All the astronomical calculations are carried out for the meridian 120 degrees east of Greenwich. This roughly corresponds to the east coast of China.

Some variations in these rules are seen in various Chinese communities.

METHOD

cycle

The number of the Chinese sexagesimal cycle

is_leap_year

True if the chinese year of the date has leap month.

gyear

The number of year in Gregorian calendar

gmonth

The number of month in Gregorian calendar

gday

The number of day in Gregorian calendar

gdate

The Gregorian calendar date.

last_day_of_month

The last day of the chinese month.

year_month_list

The month list of the chinese year. For example:

use Calendar;
$date = Calendar->new_from_China()->today();
$date->year_month_list;

The return value may like:

[[1, 732340], [2, 732370], [3, 732399], [4, 732429], [5, 732458],
 [6, 732488], [7, 732517], [7.5, 732547], [8, 732576], [9, 732606],
 [10, 732636], [11, 732665], [12, 732695]]

The element is construct from month and absolute date. So the first element is the date of chinese new year.

FUNCTIONS

timezone

Return chinese timezone. This is an expression in `year' since it changed at 1928-01-01 00:00:00 from UT+7:45:40 to UT+8. Default is for Beijing.

next_jieqi_date

Calculate next jieqi from the date.

AUTHOR

Ye Wenbin <wenbinye@gmail.com>

COPYRIGHT

Copyright (C) 2006 by ywb

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.