Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Calendar::ChUsereContributed Perl DocuDateTime::Calendar::Chinese(3)

NAME
       DateTime::Calendar::Chinese - Traditional Chinese Calendar
       Implementation

SYNOPSIS
	 use DateTime::Calendar::Chinese;

	 my $dt	= DateTime::Calendar::Chinese->now();
	 my $dt	= DateTime::Calendar::Chinese->new(
	   cycle      => $cycle,
	   cycle_year => $cycle_year,
	   month      => $month,
	   leap_month => $leap_month,
	   day	      => $day,
	 );

	 $dt->cycle;
	 $dt->cycle_year; # 1 -	60
	 $dt->month;	  # 1-12
	 $dt->leap_month; # true/false
	 $dt->day;	  # 1-30
	 $dt->elapsed_years; # years since "Chinese Epoch"

	 my ($rd_days, $rd_secs, $rd_nanosecs) = $dt->utc_rd_values();

DESCRIPTION
       This is an implementation of the	Chinese	calendar as described in
       "Calendrical Calculations" [1]. Please note that	the following
       description is the description from [1],	and the	author has not made
       attempts	to verify the correctness of statements	with other sources.

       The Chinese calendar described in [1] is	expressed in terms of "cycle",
       "cycle_year", "month", "a boolean leap_month", and "day".

       Traditional Chinese years have been counted using the "Sexagecimal
       Cycle of	Names",	which is a cycle of 60 names for each year. The	names
       are the combination of a	"celestial stem" (tian1	gan1), with a
       "terrestrial branch" (di4 zhi1):

	   Celestial Stems	   Terrestrial Branches
	 -------------------	 -----------------------
	 | Jia3		   |	 | Zi (Rat)	       |
	 -------------------	 -----------------------
	 | Yi3		   |	 | Chou3 (Ox)	       |
	 -------------------	 -----------------------
	 | Bing3	   |	 | Yin2	(Tiger)	       |
	 -------------------	 -----------------------
	 | Ding1	   |	 | Mao3	(Hare)	       |
	 -------------------	 -----------------------
	 | Wu4		   |	 | Chen2 (Dragon)      |
	 -------------------	 -----------------------
	 | Ji3		   |	 | Si4 (Snake)	       |
	 -------------------	 -----------------------
	 | Geng1	   |	 | Wu3 (Horse)	       |
	 -------------------	 -----------------------
	 | Xin1		   |	 | Wei4	(Sheep)	       |
	 -------------------	 -----------------------
	 | Ren2		   |	 | Shen1 (Monkey)      |
	 -------------------	 -----------------------
	 | Gui3		   |	 | You3	(Fowl)	       |
	 -------------------	 -----------------------
				 | Xu1 (Dog)	       |
				 -----------------------
				 | Hai4	(Pig)	       |
				 -----------------------

       Names are assigned by running each list sequentially, so	the first year
       woud be jia1zi, then yi3chou3, bing1yin2, and so	on.  The numbers after
       each syllable indicates the tone	used for the syllable.

       The animal names	of the Chinese "Zodiac"	are not	translations of	the
       terrestrial branches, which have	different meanings.  For example, the
       first branch, "zi", can mean "child" or "son", as well as several other
       things.

       Chinese months are true lunar months, which starts on a new moon	and
       runs until the day before the next new moon. Therefore each month
       consists	of exactly 29 or 30 days. The month numbers are	calculated
       based on	a logic	that combines lunar months and solar terms (which is
       too hard	to explain here	-- read	"Calendrical Calculation" if you must
       know), and may include leap months.

       Leap months can be inserted anywhere in the year, so months are
       numbered	from 1 to 12, with the boolean flag "leap_month" that
       indicates if the	month is a leap	month or not.

METHODS
   new
       This class method accepts parameters for	each date and time component:
       "cycle",	"cycle_year", "month", "leap_month", "day", "hour", "minute",
       "second", "nanosecond". It also accepts "locale"	and "time_zone"
       parameters.

       Note that in order to avoid confusion between the official Chinese
       Calendar	which is based on Chinese time zone, the default value for
       time_zone is *not* "floating", but is instead "Asia/Shanghai". See
       CAVEATS.

	 XXX The time zone settings may	change in a few	ture version such
	 XXX that the calculation is done in Asia/Shanghai, but	the
	 XXX resulting object is set to	"floating" time	zone.

       Note that currently there's no way to verify if a given date is
       "correct" -- i.e. if you	give a date as a leap_month when it in fact
       isn't a leap month, all sorts of	wacky things will happen. Perhaps
       there's a simple	way to do this.	If there is, please let	me know

   now
       This class method is equivalent to calling from_epoch() with the	value
       returned	from Perl's time() function.

   from_object(object => ...)
       This class method can be	used to	construct a new
       DateTime::Calendar::Chinese object from any object that implements the
       utc_rd_values() method.

   from_epoch(epoch => ...)
       This class method can be	used to	construct a new
       DateTime::Calendar::Chinese object from an epoch	time instead of
       components.

   set(...)
       This method is identical	to that	of DateTime, except the	date
       components that can be set are restricted to the	Chinese	ones ("cycle",
       "cycle_year", "month", "leap_month", "day"). The	time components	are
       the same	as that	of DateTime (See CAVEATS).

   set_time_zone
       Sets the	time zone. This	method is identical to that of DateTime.

   time_zone
       Gets the	time zone. This	method is identical to that of DateTime.

   utc_rd_values()
       Returns the current UTC Rata Die	days, seconds, and nanoseconds as a
       three element list. This	method is identical to that of DateTime.

   cycle
       Returns the current cycle of the	sexagecimal names since	the Chinese
       epoch (defined to be 25 Feb, -2636 gregorian).

   cycle_year
       Returns the current year	in the current cycle.

   month
       Returns the current lunar month.

   leap_month
       Returns true if the current month is a leap month.

   day
       Returns the current day in the lunar month.

   elapsed_year
       This returns the	number of years	elapsed	since the Chinese Epoch	as
       defined by [1] (Which is	15 Feb.	-2646 gregorian). Some documents use
       different epoch dates, and hence	this may not match with	whatever
       source you have.

   year_name
       Returns the name	of the year (the celestial stem	and the	terrestrial
       branch) as UTF8 (or a sequence of bytes in Perl 5.00503).

   celestial_stem
       Returns the celestial stem as UTF8 (or a	sequence of bytes in Perl
       5.00503).

   terrestrial_branch
       Returns the terrestrial branch as UTF8 (or a sequence of	bytes in Perl
       5.00503).

   year_name_py
   celestial_stem_py
   terrestrial_branch_py
       These methods return the	various	names in Pinyin, with the tones	given
       as numbers at the end of	each syllable.	The first terrestrial branch
       is generally pronounced without a tone, and is returned as "zi".

   zodiac_animal
       Returns the year's Zodiac animal.

   day_of_week
   elapsed_years
   hour
   minute
   second
   nanosecond
CAVEATS
   TIMEZONES
       Be careful with time zones! The "official" Chinese Calendar is based on
       date/time in China, not your local time zone nor	"floating" time	zone.
       This is because the Chinese Calendar is based on	astronomical events,
       but dates such as Chinese New Year are calculated in Chinese time and
       then transferred	over to	wherever you're	at.

       For example, the	Chinese	New Year in 2004 is Jan	22, but	that is	Jan 22
       in China	time. The same time is Jan 21 UTC, and now you'd be off	by one
       day.

       So when you're calculating Chinese Calendars, always set	the time zone
       to something like 'Asia/Hong_Kong', 'Asia/Shanghai', 'Asia/Taipei'

   TIME
       Because "Calendrical Calculations" did not go much in detail about the
       Chinese time system, this module	simply uses the	time components	from
       the underlying DateTime module (XXX - Note: we may implement this
       later, so be careful not	to use the time	components too much for	now)

   PERFORMANCE
       Yes, this module	is slow, because the underlying	calculations are slow.
       If you can contribute to	the speed, please let me know. So far I've
       concentrated on porting the algorithms from [1] straight	over, and not
       on performance. I'm sure	there's	a lot that could be done.

AUTHOR
       (c) Copyright 2004-2007 Daisuke Maki <daisuke@endeworks.jp>.

LICENSE
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       See http://www.perl.com/perl/misc/Artistic.html

REFERENCES
	 [1] Edward M. Reingold, Nachum	Dershowitz
	     "Calendrical Calculations (Millenium Edition)", 2nd ed.
	      Cambridge	University Press, Cambridge, UK	2002

SEE ALSO
       DateTime	DateTime::Event::Chinese

perl v5.32.1			  2011-11-29	DateTime::Calendar::Chinese(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CAVEATS | AUTHOR | LICENSE | REFERENCES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Calendar::Chinese&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help