1Date::Manip::Holidays(3U)ser Contributed Perl DocumentatiDoante::Manip::Holidays(3)
2
6 Date::Manip::Holidays - describes holidays and events
7
9 This describes the Holidays and Events sections of the config file, and
10 how they are used.
11 Holidays and events are specific days that are named. Holidays are used
13 in business mode calculations, events are not. Events may be used for
14 other calendaring operations.
15
17 The holiday section of the config file is used to define holidays.
18 Each line is of the form:
19 STRING = HOLIDAY
21 HOLIDAY is the name of the holiday or it can be blank.
23 If HOLIDAY is blank, the holiday is unnamed, but still treated as a
25 holiday. For example, in the US, the day after Thanksgiving is often a
26 work holiday though it is not named.
27 HOLIDAY should be unique in most cases. The only exception is if the
29 holiday definition is complex enough that it is impossible to describe
30 it with one STRING. In this case, multiple lines may be given with
31 different values of STRING but the same value for HOLIDAY, and in these
32 cases, the first STRING that matches a given year will be used. This
33 situation is described in more detail below.
34 NOTE: It is not allowed to have unnamed holidays that require multiple
36 definitions, so a name will have to be assigned in that case.
37 STRING is a string which can be parsed to give a valid date. It can be
39 any of the following forms:
40 A full date
42 Specific holidays can be set which occur only a single time.
43 May 5, 2000 = A one-time-only holiday
45 Any format parseable by "Date::Manip::Date::parse_date" can be
47 used.
48 There is one caveat to using a full date. Date::Manip assumes that
50 most holidays will appear once per year, so if you were to
51 explicitly defined New Years (observed) as:
52 2004-12-31 = New Year's Day
54 then it would assume that it had found the occurrence of New Year's
56 for 2004 when in fact, this is the 2005 occurrence.
57 Full date specifications should only be used as a last resort, and
59 probably only if you will explicitly specify all occurrence of the
60 holiday.
61 A date without a year
63 Some holidays occur every year on the same day. These can be
64 defined using the simple lines:
65 Jan 1 = New Year's Day
67 Jul 4th = Independence Day
68 fourth Thu in Nov = Thanksgiving
69 These dates must be written in a form which can be parsed as a full
71 date by simply adding the year to the end of the string. Please
72 refer to the Date::Manip::Date documentation to see what forms will
73 work. ISO 8601 dates will not work since the year comes first.
74 Any format parseable by "Date::Manip::Date::parse_date" which
76 allows the year to be at the end can be used.
77 Recurrence
79 The dates can be specified using recurrences:
80 1*0:0:0:0:0:0*EASTER = Easter
82 1*11:0:11:0:0:0*DWD = Veteran's Day
83 1*11:4:4:0:0:0 = Thanksgiving
84 1*11:4:4:0:0:0*FD1 = Day after Thanksgiving
85 In cases where you are interested in business type calculations,
87 you'll want to define most holidays using recurrences, since they
88 can define when a holiday is celebrated in the financial world.
89 For example, Christmas might be defined as:
90 Dec 25 = Christmas
92 but if it falls on a weekend, there won't be a business holiday
94 associated with it. It could be defined using a recurrence:
95 1*12:0:24:0:0:0*DWD = Christmas
97 so that if Christmas falls on a weekend, a holiday will be taken on
99 the Friday before or the Monday after the weekend.
100 You can use the fully specified format of a recurrence:
102 1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002
104
106 Recurrences which change years
107 It is now valid to have a recurrence defined for New Year's day
108 which pushes the holiday to the previous year.
109 For example, the most useful definition of New Year's day is:
111 1*1:0:1:0:0:0*DWD = New Year's Day
113 which means to choose the closest working day to observe the
115 holiday, even though this might mean that the holiday is observed
116 on the previous year.
117 Order of definitions is preserved
119 The order of the definitions is preserved. In other words, when
120 looking at the holidays for a year, previously defined holidays (in
121 the order given in the config file) are correctly handled.
122 As an example, if you wanted to define both Christmas and Boxing
124 days (Boxing is the day after Christmas, and is celebrated in some
125 parts of the world), and you wanted to celebrate Christmas on a
126 business day on or after Dec 25, and Boxing day as the following
127 work day, you could do it in one of the following ways:
128 1*12:0:25:0:0:0*NWD = Christmas
130 1*12:0:26:0:0:0*NWD = Boxing
131 or
133 1*12:0:25:0:0:0*NWD = Christmas
135 1*12:0:25:0:0:0*NWD = Boxing
136 Holidays go into affect the minute they are parsed which is why the
138 second example works (though for clarity, the first one is
139 preferable). The first recurrence defined the first business day
140 on or after Dec 25 as Christmas. The second one then defines the
141 business day after that as Boxing day. Since the definitions are
142 stored as a list (NOT a hash as they were in Date::Manip 5.xx),
143 using the same recurrence twice does not cause a problem.
144 Multiple holidays
146 Having multiple holidays on a single day is allowed. As an example,
147 you may want to look at New Years day as both the observed and
148 actual holidays, so you might have:
149 1*1:0:1:0:0:0*DWD = New Year's Day (observed)
151 Jan 1 = New Year's Day
152 Most of the time, both will fall on the same day, but sometimes
154 they may differ. In this example, it is important that the
155 observed holiday be listed first. Otherwise, Jan 1 will be marked
156 as a holiday and then the observed date will check Jan 1, but where
157 it is not a business day, it will move to another day (due to the
158 DWD modifier).
159 Likewise, the two holidays:
161 3rd Sunday in June = Father's Day
163 Jun 17 = Bunker Hill Day
164 sometimes fall on the same day. Using the
166 "Date::Manip::Date::list_holidays" method (or the "Date_IsHoliday"
167 function), you can get a list of all names that the date contains.
168 Complex holiday descriptions
170 Occasionally, you cannot describe a holiday using a single line.
171 For example, the US Federal Reserve banks use a complex holiday
172 description where:
173 For holidays falling on Saturday, Federal Reserve Banks
175 and Branches will be open the preceding Friday. For holidays
176 falling on Sunday, all Federal Reserve Banks and Branches
177 will be closed the following Monday.
178 Since Saturday is not a business day, the DWD modifier will not
180 work. For these, you need a more complicated definition.
181 The following definitions both work:
183 # Saturday
185 1*1:0:1:0:0:0*NBD,BD1,IBD,FD1 = New Year's Day
186 # Sunday (observed Monday)
187 1*1:0:1:0:0:0*NBD,BD1,NBD,FD2 = New Year's Day
188 # M-F
189 1*1:0:1:0:0:0*IBD = New Year's Day
190 and
192 # Saturday
194 1*1:0:1:0:0:0*IW6 = New Year's Day
195 # Sunday (observed Monday)
196 1*1:0:1:0:0:0*IW7,FD1 = New Year's Day
197 # M-F
198 1*1:0:1:0:0:0*IBD = New Year's Day
199
201 The Events section of the config file is similar to the Holiday
202 section. It is used to name certain days or times, but there are a few
203 important differences:
204 Events can be assigned to any time and duration
206 All holidays are exactly 1 day long. They are assigned to a period
207 of time from midnight to midnight.
208 Events can be based at any time of the day, and may be of any
210 duration.
211 Events don't affect business mode calculations
213 Unlike holidays, events are completely ignored when doing business
214 mode calculations.
215 Whereas holidays were added with business mode math in mind, events
217 were added with calendar and scheduling applications in mind.
218 Every line in the events section is of the form:
220 EVENT = NAME
222 where NAME is the name of the event, and EVENT defines when it occurs
224 and its duration. An EVENT can be defined in the following ways:
225 Date
227 YMD
228 YM
229 Recur
230 Date ; Date
232 YMD ; YMD
233 YM ; YM
234 Date ; Delta
235 Recur ; Delta
236 Date refers to a full date/time (and is any string that can be parsed
238 by "Date::Manip::Date::parse"). YMD is any string which can be parsed
239 by "Date::Manip::Date::parse_date". YM is any string which can be
240 parsed by the parse_date method to give a date in the current year.
241 Recur is a partial or fully specified recurrence. Delta is any string
242 that can be parsed to form a delta.
243 With the "Date" form, or the "Recur" form, the event starts at the time
245 (or times) specified by the date or recurrence, and last 1 hour long.
246 With the "YMD" and "YM" forms, the event occurs on the given day, and
247 lasts all day.
248 With all of the two part forms ("Date;Date", "YM;YM", etc.), the event
250 starts at the first date and goes to the second date, or goes an amount
251 of time specified by the delta.
252 The "YMD;YMD" and "YM;YM" forms means that the event lasts from the
254 start of the first date to the end of the second. In the Date;Date
255 form, the event goes from the first date to the second date inclusive.
256 In other words, both dates are in the event. In the "Date;Delta" and
257 "Recur;Delta" forms, the Delta tells the length of the event. Also, in
258 the Date;Date form, the second date may NOT be expressed as a delta.
259 Currently, having an event longer than 1 year is NOT supported, but no
261 checking is done for this.
262
264 None known.
265
267 Please refer to the Date::Manip::Problems documentation for information
268 on submitting bug reports or questions to the author.
269
271 Date::Manip - main module documentation
272
274 This script is free software; you can redistribute it and/or modify it
275 under the same terms as Perl itself.
276
278 Sullivan Beck (sbeck@cpan.org)
279perl v5.34.1 2022-06-06 Date::Manip::Holidays(3)