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

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Event::EasteUser Contributed Perl DocumentDateTime::Event::Easter(3)

NAME
       DateTime::Event::Easter - Returns Easter	events for DateTime objects

SYNOPSIS
	 use DateTime::Event::Easter;

	 $dt = DateTime->new( year   =>	2002,
			      month  =>	   3,
			      day    =>	  31,
			    );

	 $easter_sunday	= DateTime::Event::Easter->new();

	 $previous_easter_sunday = $easter_sunday->previous($dt);
	 # Sun,	15 Apr 2001 00:00:00 UTC

	 $following_easter_sunday = $easter_sunday->following($dt);
	 # Sun,	20 Apr 2003 00:00:00 UTC

	 $closest_easter_sunday	= $easter_sunday->closest($dt);
	 # Sun,	31 Mar 2002 00:00:00 UTC

	 $is_easter_sunday = $easter_sunday->is($dt);
	 # 1

	 $palm_sunday =	DateTime::Event::Easter->new(day => 'Palm Sunday');

	 $dt2 =	DateTime->new( year   => 2006,
			       month  =>    4,
			       day    =>   30,
			     );

	 $set  = $palm_sunday->as_set (from => $dt, to => $dt2,	inclusive => 1);
	 @list = $palm_sunday->as_list(from => $dt, to => $dt2,	inclusive => 1);
	 # Sun,	13 Apr 2003 00:00:00 UTC
	 # Sun,	04 Apr 2004 00:00:00 UTC
	 # Sun,	20 Mar 2005 00:00:00 UTC
	 # Sun,	09 Apr 2006 00:00:00 UTC

	 $datetime_set = $palm_sunday->as_set;
	 # A set of every Palm Sunday ever. See	DateTime::Set for more information.

DESCRIPTION
       The DateTime::Event::Easter module returns Easter events	for DateTime
       objects.	From a given datetime, it can tell you the previous, the
       following and the closest Easter	event. The 'is'	method will tell you
       if the given DateTime is	an Easter Event.

       Easter Events can be Fat	Tuesday, Ash Wednesday,	Palm Sunday, Maundy
       Thursday, Good Friday, Black Saturday, Easter Sunday, Ascension,
       Pentecost and Trinity Sunday. If	that's not enough, the module will
       also accept an offset so	you can	get the	date for Quasimodo (the	next
       sunday after Easter Sunday) by passing 7.

BACKGROUND
       Easter Sunday is	the Sunday following the first full moon on or
       following the Official Vernal Equinox. The Official Vernal Equinox is
       March 21st. Easter Sunday is never on the full moon. Thus the earliest
       Easter can be is	March 22nd.

       In the orthodox world, although they now	use the	Gregorian Calendar
       rather than the Julian, they still take the first full moon on or after
       the Julian March	21st. As the Julian calendar is	slowly getting further
       and further out of sync with the	Gregorian, the first full moon after
       this date can be	a completely different one than	for the	western
       Easter. This is why the Orthodox	churches celebrate Easter later	than
       western churches.

CONSTRUCTOR
   "new" constructor
       This class accepts the following	options	to its "new" constructor:

       o   easter => ([western]|eastern)

	   DateTime::Event::Easter understands two calculations	for Easter.
	   For simplicity we've	called them 'western' and 'eastern'.

	   Western Easter is the day celebrated	by the Catholic	and Protestant
	   churches. It	falls on the first Sunday after	the first Full Moon on
	   or after March 21st.

	   Eastern Easter, as celebrated by the	Eastern	Orthodox Churches
	   similarly falls on the first	Sunday after the first Full Moon on or
	   after March 21st. However Eastern Easter uses March 21st in the
	   Julian Calendar.

	   By default this module uses the Western Easter. Even	if you pass a
	   Julian DateTime to the module, you'll get back Western Easter
	   unless you specifically ask for Eastern.

	   If this parameter is	not supplied, the western Easter will be used.

       o   day => ([Easter Sunday]|Palm	Sunday|Maundy Thursday|Good
	   Friday|Black	Saturday|Fat Tuesday|Ash
	   Wednesday|Ascension|Pentecost|Trinity Sunday|n)

	   When	constructed with a day parameter, the method can return
	   associated Easter days other	than Easter Sunday. The	constructor
	   also	allows an integer to be	passed here as an offset. For example,
	   Maundy Thursday is the same as an offset of -3 (Three days before
	   Easter Sunday)

	   When	constructed without a day parameter, the method	uses the date
	   for Easter Sunday (which is the churches' official day for
	   'Easter', think of it a 'Easter Day'	if you want)

	   This	parameter also allows the following abreviations: day =>
	   ([Sunday]|Palm|Thursday|Friday|Saturday|Fat|Ash|Ascension|Pentecost|Trinity)

       o   as => ([point]|span)

	   By default, all returns are single points in	time. Namely they are
	   the moment of midnight for the day in question. If you want Easter
	   2003	then you actually get back midnight of April 20th 2003.	If you
	   specify "as => 'span'" in your constructor, you'll now receive 24
	   hour	spans rather than moments (or 'points'). See also the
	   "as_span" and "as_point" methods below

METHODS
       For all these methods, unless otherwise noted, $dt is a plain vanilla
       DateTime	object or a DateTime object from any DateTime::Calendar	module
       that can	handle calls to	"from_object" and "utc_rd_values" (which
       should be all of	them, but there's nothing stopping someone making a
       bad egg).

       This class offers the following methods.

       o   following($dt)

	   Returns the DateTime	object for the Easter Event after $dt. This
	   will	not return $dt.

       o   previous($dt)

	   Returns the DateTime	object for the Easter Event before $dt.	This
	   will	not return $dt.

       o   closest($dt)

	   Returns the DateTime	object for the Easter Event closest to $dt.
	   This	will return midnight of	$dt if $dt is the Easter Event.

       o   is($dt)

	   Return true (1) if $dt is the Easter	Event, otherwise returns false
	   (0)

       o   as_list(from	=> $dt,	to => $dt2, inclusive => ([0]|1))

	   Returns a list of Easter Events between from	and to.

	   If the optional inclusive parameter is true (non-zero), the to and
	   from	dates will be included if they are the Easter Event.

	   If you do not include an inclusive parameter, we assume you do not
	   want	to include these dates (the same behaviour as supplying	a
	   false value)

       o   as_set()

	   Returns a DateTime::Set of Easter Events.

	   In  the past	 this method  used the	same syntax  as	'as_list'
	   above.  However we now allow	both the above syntax as well as the
	   full	options	allowable when creating	sets with "DateTime::Set".
	   This	means you can call "$datetime_set = $palm_sunday->as_set;" and
	   it will return a "DateTime::Set" of	all Palm  Sundays. See
	   DateTime::Set  for more information.

       o   as_span()

	   This	method switches	output to spans	rather than points. See	the
	   'as'	attribute of the constructor for more information. The method
	   returns the object for easy chaining.

       o   as_point()

	   This	method switches	output to points rather	than spans. See	the
	   'as'	attribute of the constructor for more information. The method
	   returns the object for easy chaining.

       o   as_old_set()

	   Deprecated method.

	   In the  next	version	(1.10)	or in October  2021 (two years	after
	   the v1.08 initial  announcement), whichever	comes last, this
	   method will emit  a warning.	 And within  another two  years	/  one
	   version,  this method will be removed.

SUBROUTINES
       The  module provides  a few  subroutines	giving	the elements  used to
       compute the Easter date.

       These  elements can  be found  in various  sources, including  what is
       known in	France as l'Almanach  du Facteur (the postman's	almanach).
       These values are	printed	at the bottom of the February frame, which is
       a  convenient way  to ensure  this frame	 has the  same height  as the
       frames for 31-day months.

       These subroutines are not exported by default.

       o   golden_number($year)

	   Gives the position of  the year in the Metonic cycle.  This is a
	   1..19 number.

	   This	subroutine applies to both western and eastern computs.

       o   western_epact($year)

	   In the  Gregorian comput, the epact	is the age of  the
	   ecclesiastical Moon on the 1st January of the  given	year. The
	   "western" part of the subroutine  name  accounts for	 the  fact
	   that	Gregorian  and	Julian calendars do not	use the	same formula.

	   The epact  is a 0..29 number.  The "0" value	 is shown as "*"  in
	   some	sources. This  subroutine does not convert  "0"	to "*",	the
	   result is always a pure number.

	   Actually,  the western  epact  is  a	little	more  than  a number.
	   As explained	by Paul	Couderc	(page 86)  and Jean Lefort (page 142),
	   there is a  special case for	25,  which should be considered	 as
	   two values, "basic 25" and "alternate 25". "Basic 25" is printed as
	   a plain number 25, while "alternate 25" is printed  in a way	that
	   distinguishes it from the other  numbers. Jean Lefort mentions
	   "XXV"  or using italics or bold  digits, such as  25. This module
	   prints  the "alternate 25" as ""25*"".

       o   eastern_epact($year)

	   In the Julian comput, the epact  is the age of the ecclesiastical
	   Moon	on 22nd	March. The "eastern" part of the subroutine name
	   accounts for	the  fact that	Gregorian and  Julian calendars	 do
	   not	use the	 same formula.

	   The epact  is a 0..29 number.  The "0" value	 is shown as "*"  in
	   some	sources. This  subroutine does not convert  "0"	to "*",	the
	   result is always a pure  number. There is no	 other special case,
	   for	25 as for any other number.

	   The formula given by	Reingold and  Dershowitz is a "shifted epact"
	   and gives  different	 results from  the  values  printed in
	   Lefort's  and Couderc's books. The module follows Couderc and
	   Lefort.

       o   western_sunday_letter($year), eastern_sunday_letter($year)

	   On normal years (that is, excluding	leap years), the Sunday	letter
	   is determined by tagging 1st	January	with  "A", 2nd January with
	   "B",	and so on and looking at the first sunday of the year. The
	   letter found	at this	sunday if the sunday letter for	the year.

	   The	sunday	 letter	 governs  all	conversions  from  (mm,	  dd)
	   to day-of-week. For example,	if the letter is "F", then 1st
	   January, 12th February, 2nd July and	1st  October, among others,
	   are tuesdays, while 6th January, 24th February, 14th	July and 6th
	   October are sundays.

	   On  leap  years, there  are	two  sunday  letters.  The first  one
	   is determined  as above,  the second	 one  is determined  by
	   tagging  2nd	January,  not 1st,  with  "A".	The first  sunday
	   letter governs  all conversions  from (mm,  dd) to  day-of-week for
	   January and	February only, while the second	sunday letter governs
	   the conversions from	(mm, dd) to day-of-week	for March and after.

	   So, if the sunday letters are  "FE",	1st January and	12th February
	   are still tuesdays,	but 2nd	July and  1st October are wednesdays.
	   At the same time, 6th January and 24th February are still sundays,
	   while 14th July and 6th October are mondays.

	   "western_sunday_letter"  applies  only   to	Gregorian  years,
	   while "eastern_sunday_letter" applies only to Julian	years.

       o   western_sunday_number($year), eastern_sunday_number($year)

	   Letters  (standalone	or  in pairs)  are not	convenient for
	   numerical calculations.  So	the   xxx"_sunday_number"  subroutine
	   is  used instead of xxx"_sunday_letter".

	   In case  of leap  years, the	xxx"_sunday_number"  subroutine	gives
	   the numerical value for the second sunday letter, because Easter
	   never falls in January or February.

       o   easter($year)

	   Given a Gregorian year, this	 subroutine will return	a DateTime
	   object for Western Easter Sunday in that year.

       o   western_easter($year)

	   Given a Gregorian year, this	 subroutine will return	a DateTime
	   object for  Western Easter  Sunday  in  that	year.  But  unlike the
	   previous subroutine,	 "western_easter" cannot  be imported.	You
	   must	 use its fully qualified name:

	     my	$date =	DateTime::Event::Easter::western_easter($year);

       o   eastern_easter($year)

	   Given  a  Julian year,  this	 subroutine  will  return a  DateTime
	   :: Calendar :: Julian object	for Eastern  Easter Sunday in that
	   year. And like "western_easter", "eastern_easter" cannot be
	   imported. You must use its fully qualified name:

	     my	$date =	DateTime::Event::Easter::eastern_easter($year);

BUGS AND PROBLEMS FOR SPANS
   Inclusion and exclusion of "from" and "to" dates in lists and sets
       If you build a list or a	set of spans and if the	"from" or "to" limits
       coincide	with the requested Easter event, the result may	be different
       from what you expect. For example, you ask for Easter sundays between
       2017-04-16T21:43:00 and 2020-04-12T12:34:00.

       The inclusive list or set will be:

	 2017-04-16T00:00:00 to	2017-04-16T23:59:59
	 2018-04-01T00:00:00 to	2018-04-01T23:59:59
	 2019-04-21T00:00:00 to	2019-04-21T23:59:59
	 2020-04-12T00:00:00 to	2020-04-12T23:59:59

       and not:

	 2017-04-16T21:43:00 to	2017-04-16T23:59:59
	 2018-04-01T00:00:00 to	2018-04-01T23:59:59
	 2019-04-21T00:00:00 to	2019-04-21T23:59:59
	 2020-04-12T00:00:00 to	2020-04-12T12:34:00

       The exclusive list or set will be:

	 2018-04-01T00:00:00 to	2018-04-01T23:59:59
	 2019-04-21T00:00:00 to	2019-04-21T23:59:59

       and not:

	 2017-04-16T21:43:01 to	2017-04-16T23:59:59
	 2018-04-01T00:00:00 to	2018-04-01T23:59:59
	 2019-04-21T00:00:00 to	2019-04-21T23:59:59
	 2020-04-12T00:00:00 to	2020-04-12T12:35:59

       Remarks and patches welcome.

       Note for	pedants: the hour "21:43:01" should actually be	21 hours, 43
       minutes,	zero seconds and 1 nanosecond.	Likewise, all the times	above
       ending with ":59" include 999_999_999 nanoseconds.

   Interaction of spans	with timezones
       It may happen that Palm sunday or Easter	sunday coincide	with DST
       "spring forward"	day (for Northern countries). I	have not checked what
       happens in this case for	spans: a bit more than one day for exactly 24
       hours or	exactly	one day	which gives 23 hours?  A similar question
       exists for DST "fall backward" day in the Southern countries.

       Also, since  you	can use	 a numeric  "day" offset beyond	 the Trinity
       sunday, you can	reach the Northern "fall backwards"  and the Southern
       "spring forward"	days, where the	same problem will happen in reverse.

THE SMALL PRINT
   REFERENCES
       o   <https://github.com/houseabsolute/DateTime.pm/wiki> - The official
	   wiki	of the DateTime	project

       o   <https://www.tondering.dk/claus/calendar.html> - Claus TA,ndering's
	   calendar FAQ, especially the	page
	   <https://www.tondering.dk/claus/cal/easter.php>.

       o   Calendrical Calculations (Third or Fourth Edition) by Nachum
	   Dershowitz and Edward M. Reingold, Cambridge	University Press, see
	   <http://www.calendarists.com> or
	   <https://www.cambridge.org/us/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition?format=PB&isbn=9781107683167>,
	   ISBN	978-0-521-70238-6 for the third	edition.

       o   La saga des calendriers, by Jean Lefort, published by Belin (Pour
	   la Science),	ISBN 2-90929-003-5 See
	   <https://www.belin-editeur.com/la-saga-des-calendriers>

       o   Le Calendrier, by Paul Couderc, published by	Presses	universitaires
	   de France (Que sais-je ?), ISBN 2-13-036266-4 See
	   <https://catalogue.bnf.fr/ark:/12148/cb329699661>.

   SUPPORT
       Support for this	module,	and for	all DateTime modules will be given
       through the DateTime mailing list - datetime@perl.org.  See
       <https://lists.perl.org/list/datetime.html>.

       Bugs should be reported through rt.cpan.org. See
       <https://rt.cpan.org/Public/Dist/Display.html?Name=DateTime-Event-Easter>.

       Or you can try to submit	a pull request to
       <https://github.com/jforget/DateTime-Event-Easter>.

   AUTHOR
       Rick Measham <rickm@cpan.org>

       Co-maintainer Jean Forget <jforget@cpan.org>

   CREDITS
       Much help from the DateTime mailing list, especially from:

       Eugene van der Pijll - who pointed out flaws causing errors on
       gregorian years with no eastern easter (like 35000) and who came	up
       with a patch to make the	module accept any calendar's DateTime object

       Dave Rolsky - who picked	nits, designed DateTime	itself and leads the
       project

       Martin Hasch - who pointed out the posibility of	memory leak with an
       early beta

       Joe Orost and Andreas K~A<paragraph>nig -	for RT tickets about the POD
       documentation

       Frank Wiegand and Slaven	Rezi"A -	for patches fixing the POD problems

       Tom Wyant -  for	a constructive dialog about  the relations between
       DateTime::Calendar::Julian   (versions	0.101	and   0.102)   and
       DateTime::Event::Easter (versions 1.08 and 1.09)

       Andreas K~A<paragraph>nig	 (again) - for	a message  a long time	ago
       (December 2010)	  in	which	 he    told   me    about    his
       web    site <http://analysis.cpantesters.org/> which  was very useful
       nine years later	for debugging DT::E::Easter version 1.08.

   COPYRIGHT
       A(C) Copyright 2003, 2004, 2015,	2019 Rick Measham and Jean Forget. All
       rights reserved.	This program is	free software; you can redistribute it
       and/or modify it	under the same terms as	Perl itself: GNU Public
       License version 1 or later and Perl Artistic License.

       The full	text of	the license can	be found in the	LICENSE	file included
       with this module	or at <https://dev.perl.org/licenses/artistic.html>
       and <https://www.gnu.org/licenses/gpl-1.0.html>.

       Here is the summary of GPL:

       This program is	free software; you can redistribute  it	and/or modify
       it under	the  terms of the GNU General Public  License as published by
       the Free	 Software Foundation; either  version 1, or (at	 your option)
       any later version.

       This program  is	distributed in the  hope that it will  be useful, but
       WITHOUT	 ANY  WARRANTY;	  without  even	  the  implied	 warranty  of
       MERCHANTABILITY	or FITNESS  FOR	A  PARTICULAR PURPOSE.	 See  the GNU
       General Public License for more details.

       You  should have	received  a copy  of the  GNU General  Public License
       along with this program;	if not,	see <https://www.gnu.org/licenses/> or
       write to	the Free Software Foundation, Inc., <https://fsf.org>.

   SEE ALSO
       DateTime, DateTime::Calendar::Julian, perl(1)

       <https://metacpan.org/search?q=easter> which gives Date::Easter,
       Date::Calc and Date::Pcalc

       <https://github.com/houseabsolute/DateTime.pm/wiki>

perl v5.32.1			  2019-11-12	    DateTime::Event::Easter(3)

NAME | SYNOPSIS | DESCRIPTION | BACKGROUND | CONSTRUCTOR | METHODS | SUBROUTINES | BUGS AND PROBLEMS FOR SPANS | THE SMALL PRINT

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

home | help