- BUGS AND PROBLEMS FOR SPANS
- THE SMALL PRINT
DateTime::Event::Easter - Returns Easter events for DateTime objects
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.
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.
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.
This class accepts the following options to its
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.
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)
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
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
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.
Returns the DateTime object for the Easter Event after
$dt. This will not return
Returns the DateTime object for the Easter Event before
$dt. This will not return
Returns the DateTime object for the Easter Event closest to
$dt. This will return midnight of
$dtis the Easter Event.
Return true (1) if
$dtis the Easter Event, otherwise returns false (0)
as_list(from => $dt, to => $dt2, inclusive => (|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)
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::Setof all Palm Sundays. See DateTime::Set for more information.
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.
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.
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.
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.
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.
In the Gregorian comput, the epact is the age of the ecclesiastical Moon on the 1st January of the given year. The
westernpart 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
XXVor using italics or bold digits, such as
25. This module prints the "alternate 25" as "
In the Julian comput, the epact is the age of the ecclesiastical Moon on 22nd March. The
easternpart 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.
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_letterapplies only to Gregorian years, while
eastern_sunday_letterapplies only to Julian years.
Letters (standalone or in pairs) are not convenient for numerical calculations. So the xxx
_sunday_numbersubroutine is used instead of xxx
In case of leap years, the xxx
_sunday_numbersubroutine gives the numerical value for the second sunday letter, because Easter never falls in January or February.
Given a Gregorian year, this subroutine will return a DateTime object for Western Easter Sunday in that 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_eastercannot be imported. You must use its fully qualified name:
my $date = DateTime::Event::Easter::western_easter($year);
Given a Julian year, this subroutine will return a DateTime :: Calendar :: Julian object for Eastern Easter Sunday in that year. And like
eastern_eastercannot be imported. You must use its fully qualified name:
my $date = DateTime::Event::Easter::eastern_easter($year);
If you build a list or a set of spans and if the
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
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
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.
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.
https://github.com/houseabsolute/DateTime.pm/wiki - The official wiki of the DateTime project
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.
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
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 for this module, and for all DateTime modules will be given through the DateTime mailing list - firstname.lastname@example.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.
Rick Measham <email@example.com>
Co-maintainer Jean Forget <firstname.lastname@example.org>
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önig - for RT tickets about the POD documentation
Frank Wiegand and Slaven Rezić - for patches fixing the POD problems
Andreas Kö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 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.
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.