Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "CALC 1" | |
132 | .TH CALC 1 "2002-09-28" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Date::Calc \- Gregorian calendar date calculations | |
135 | .SH "MOTTO" | |
136 | .IX Header "MOTTO" | |
137 | Keep it small, fast and simple | |
138 | .SH "PREFACE" | |
139 | .IX Header "PREFACE" | |
140 | This package consists of a C library and a Perl module (which uses | |
141 | the C library, internally) for all kinds of date calculations based | |
142 | on the Gregorian calendar (the one used in all western countries today), | |
143 | thereby complying with all relevant norms and standards: \s-1ISO/R\s0\ 2015\-1971, | |
144 | \&\s-1DIN\s0\ 1355 and, to some extent, \s-1ISO\s0\ 8601 (where applicable). | |
145 | .PP | |
146 | (See also http://www.engelschall.com/u/sb/download/Date\-Calc/DIN1355/ | |
147 | for a scan of part of the "\s-1DIN\s0\ 1355" document (in German)). | |
148 | .PP | |
149 | The module of course handles year numbers of 2000 and above correctly | |
150 | (\*(L"Year 2000\*(R" or \*(L"Y2K\*(R" compliance) \*(-- actually all year numbers from 1 | |
151 | to the largest positive integer representable on your system (which | |
152 | is at least 32767) can be dealt with. | |
153 | .PP | |
154 | This is not true, however, for the import/export functions in this | |
155 | package which are an interface to the internal \s-1POSIX\s0 date and time | |
156 | functions of your system, which can only cover dates in the following | |
157 | ranges: | |
158 | .PP | |
159 | .Vb 3 | |
160 | \& 01-Jan-1970 00:00:00 GMT .. 19-Jan-2038 03:14:07 GMT [Unix etc.] | |
161 | \& 01-Jan-1904 00:00:00 LT .. 06-Feb-2040 06:28:15 LT [MacOS Classic] | |
162 | \& (LT = local time) | |
163 | .Ve | |
164 | .PP | |
165 | Note that this package projects the Gregorian calendar back until the | |
166 | year 1\ A.D. \*(-- even though the Gregorian calendar was only adopted | |
167 | in 1582, mostly by the Catholic European countries, in obedience to the | |
168 | corresponding decree of Pope Gregory\ \s-1XIII\s0 in that year. | |
169 | .PP | |
170 | Some (mainly protestant) countries continued to use the Julian calendar | |
171 | (used until then) until as late as the beginning of the 20th century. | |
172 | .PP | |
173 | Finally, note that this package is not intended to do everything you could | |
174 | ever imagine automagically for you; it is rather intended to serve as a | |
175 | toolbox (in the best of \s-1UNIX\s0 spirit and traditions) which should, however, | |
176 | always get you where you want to go. | |
177 | .PP | |
178 | See the section \*(L"\s-1RECIPES\s0\*(R" at the bottom of this document for solutions | |
179 | to common problems! | |
180 | .PP | |
181 | If nevertheless you can't figure out how to solve a particular problem, | |
182 | please let me know! (See e\-mail address at the end of this document.) | |
183 | .SH "SYNOPSIS" | |
184 | .IX Header "SYNOPSIS" | |
185 | .Vb 66 | |
186 | \& use Date::Calc qw( | |
187 | \& Days_in_Year | |
188 | \& Days_in_Month | |
189 | \& Weeks_in_Year | |
190 | \& leap_year | |
191 | \& check_date | |
192 | \& check_time | |
193 | \& check_business_date | |
194 | \& Day_of_Year | |
195 | \& Date_to_Days | |
196 | \& Day_of_Week | |
197 | \& Week_Number | |
198 | \& Week_of_Year | |
199 | \& Monday_of_Week | |
200 | \& Nth_Weekday_of_Month_Year | |
201 | \& Standard_to_Business | |
202 | \& Business_to_Standard | |
203 | \& Delta_Days | |
204 | \& Delta_DHMS | |
205 | \& Delta_YMD | |
206 | \& Delta_YMDHMS | |
207 | \& Normalize_DHMS | |
208 | \& Add_Delta_Days | |
209 | \& Add_Delta_DHMS | |
210 | \& Add_Delta_YM | |
211 | \& Add_Delta_YMD | |
212 | \& Add_Delta_YMDHMS | |
213 | \& System_Clock | |
214 | \& Today | |
215 | \& Now | |
216 | \& Today_and_Now | |
217 | \& This_Year | |
218 | \& Gmtime | |
219 | \& Localtime | |
220 | \& Mktime | |
221 | \& Timezone | |
222 | \& Date_to_Time | |
223 | \& Time_to_Date | |
224 | \& Easter_Sunday | |
225 | \& Decode_Month | |
226 | \& Decode_Day_of_Week | |
227 | \& Decode_Language | |
228 | \& Decode_Date_EU | |
229 | \& Decode_Date_US | |
230 | \& Fixed_Window | |
231 | \& Moving_Window | |
232 | \& Compress | |
233 | \& Uncompress | |
234 | \& check_compressed | |
235 | \& Compressed_to_Text | |
236 | \& Date_to_Text | |
237 | \& Date_to_Text_Long | |
238 | \& English_Ordinal | |
239 | \& Calendar | |
240 | \& Month_to_Text | |
241 | \& Day_of_Week_to_Text | |
242 | \& Day_of_Week_Abbreviation | |
243 | \& Language_to_Text | |
244 | \& Language | |
245 | \& Languages | |
246 | \& Decode_Date_EU2 | |
247 | \& Decode_Date_US2 | |
248 | \& Parse_Date | |
249 | \& ISO_LC | |
250 | \& ISO_UC | |
251 | \& ); | |
252 | .Ve | |
253 | .PP | |
254 | .Vb 1 | |
255 | \& use Date::Calc qw(:all); | |
256 | .Ve | |
257 | .PP | |
258 | .Vb 2 | |
259 | \& Days_in_Year | |
260 | \& $days = Days_in_Year($year,$month); | |
261 | .Ve | |
262 | .PP | |
263 | .Vb 2 | |
264 | \& Days_in_Month | |
265 | \& $days = Days_in_Month($year,$month); | |
266 | .Ve | |
267 | .PP | |
268 | .Vb 2 | |
269 | \& Weeks_in_Year | |
270 | \& $weeks = Weeks_in_Year($year); | |
271 | .Ve | |
272 | .PP | |
273 | .Vb 2 | |
274 | \& leap_year | |
275 | \& if (leap_year($year)) | |
276 | .Ve | |
277 | .PP | |
278 | .Vb 2 | |
279 | \& check_date | |
280 | \& if (check_date($year,$month,$day)) | |
281 | .Ve | |
282 | .PP | |
283 | .Vb 2 | |
284 | \& check_time | |
285 | \& if (check_time($hour,$min,$sec)) | |
286 | .Ve | |
287 | .PP | |
288 | .Vb 2 | |
289 | \& check_business_date | |
290 | \& if (check_business_date($year,$week,$dow)) | |
291 | .Ve | |
292 | .PP | |
293 | .Vb 2 | |
294 | \& Day_of_Year | |
295 | \& $doy = Day_of_Year($year,$month,$day); | |
296 | .Ve | |
297 | .PP | |
298 | .Vb 2 | |
299 | \& Date_to_Days | |
300 | \& $days = Date_to_Days($year,$month,$day); | |
301 | .Ve | |
302 | .PP | |
303 | .Vb 2 | |
304 | \& Day_of_Week | |
305 | \& $dow = Day_of_Week($year,$month,$day); | |
306 | .Ve | |
307 | .PP | |
308 | .Vb 2 | |
309 | \& Week_Number | |
310 | \& $week = Week_Number($year,$month,$day); # DEPRECATED | |
311 | .Ve | |
312 | .PP | |
313 | .Vb 3 | |
314 | \& Week_of_Year | |
315 | \& ($week,$year) = Week_of_Year($year,$month,$day); # RECOMMENDED | |
316 | \& $week = Week_of_Year($year,$month,$day); # DANGEROUS | |
317 | .Ve | |
318 | .PP | |
319 | .Vb 2 | |
320 | \& Monday_of_Week | |
321 | \& ($year,$month,$day) = Monday_of_Week($week,$year); | |
322 | .Ve | |
323 | .PP | |
324 | .Vb 3 | |
325 | \& Nth_Weekday_of_Month_Year | |
326 | \& if (($year,$month,$day) = | |
327 | \& Nth_Weekday_of_Month_Year($year,$month,$dow,$n)) | |
328 | .Ve | |
329 | .PP | |
330 | .Vb 3 | |
331 | \& Standard_to_Business | |
332 | \& ($year,$week,$dow) = | |
333 | \& Standard_to_Business($year,$month,$day); | |
334 | .Ve | |
335 | .PP | |
336 | .Vb 3 | |
337 | \& Business_to_Standard | |
338 | \& ($year,$month,$day) = | |
339 | \& Business_to_Standard($year,$week,$dow); | |
340 | .Ve | |
341 | .PP | |
342 | .Vb 3 | |
343 | \& Delta_Days | |
344 | \& $Dd = Delta_Days($year1,$month1,$day1, | |
345 | \& $year2,$month2,$day2); | |
346 | .Ve | |
347 | .PP | |
348 | .Vb 4 | |
349 | \& Delta_DHMS | |
350 | \& ($Dd,$Dh,$Dm,$Ds) = | |
351 | \& Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, | |
352 | \& $year2,$month2,$day2, $hour2,$min2,$sec2); | |
353 | .Ve | |
354 | .PP | |
355 | .Vb 4 | |
356 | \& Delta_YMD | |
357 | \& ($Dy,$Dm,$Dd) = | |
358 | \& Delta_YMD($year1,$month1,$day1, | |
359 | \& $year2,$month2,$day2); | |
360 | .Ve | |
361 | .PP | |
362 | .Vb 4 | |
363 | \& Delta_YMDHMS | |
364 | \& ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = | |
365 | \& Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, | |
366 | \& $year2,$month2,$day2, $hour2,$min2,$sec2); | |
367 | .Ve | |
368 | .PP | |
369 | .Vb 3 | |
370 | \& Normalize_DHMS | |
371 | \& ($Dd,$Dh,$Dm,$Ds) = | |
372 | \& Normalize_DHMS($Dd,$Dh,$Dm,$Ds); | |
373 | .Ve | |
374 | .PP | |
375 | .Vb 4 | |
376 | \& Add_Delta_Days | |
377 | \& ($year,$month,$day) = | |
378 | \& Add_Delta_Days($year,$month,$day, | |
379 | \& $Dd); | |
380 | .Ve | |
381 | .PP | |
382 | .Vb 4 | |
383 | \& Add_Delta_DHMS | |
384 | \& ($year,$month,$day, $hour,$min,$sec) = | |
385 | \& Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, | |
386 | \& $Dd,$Dh,$Dm,$Ds); | |
387 | .Ve | |
388 | .PP | |
389 | .Vb 4 | |
390 | \& Add_Delta_YM | |
391 | \& ($year,$month,$day) = | |
392 | \& Add_Delta_YM($year,$month,$day, | |
393 | \& $Dy,$Dm); | |
394 | .Ve | |
395 | .PP | |
396 | .Vb 4 | |
397 | \& Add_Delta_YMD | |
398 | \& ($year,$month,$day) = | |
399 | \& Add_Delta_YMD($year,$month,$day, | |
400 | \& $Dy,$Dm,$Dd); | |
401 | .Ve | |
402 | .PP | |
403 | .Vb 4 | |
404 | \& Add_Delta_YMDHMS | |
405 | \& ($year,$month,$day, $hour,$min,$sec) = | |
406 | \& Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, | |
407 | \& $D_y,$D_m,$D_d, $Dh,$Dm,$Ds); | |
408 | .Ve | |
409 | .PP | |
410 | .Vb 3 | |
411 | \& System_Clock | |
412 | \& ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
413 | \& System_Clock([$gmt]); | |
414 | .Ve | |
415 | .PP | |
416 | .Vb 2 | |
417 | \& Today | |
418 | \& ($year,$month,$day) = Today([$gmt]); | |
419 | .Ve | |
420 | .PP | |
421 | .Vb 2 | |
422 | \& Now | |
423 | \& ($hour,$min,$sec) = Now([$gmt]); | |
424 | .Ve | |
425 | .PP | |
426 | .Vb 2 | |
427 | \& Today_and_Now | |
428 | \& ($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]); | |
429 | .Ve | |
430 | .PP | |
431 | .Vb 2 | |
432 | \& This_Year | |
433 | \& $year = This_Year([$gmt]); | |
434 | .Ve | |
435 | .PP | |
436 | .Vb 3 | |
437 | \& Gmtime | |
438 | \& ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
439 | \& Gmtime([time]); | |
440 | .Ve | |
441 | .PP | |
442 | .Vb 3 | |
443 | \& Localtime | |
444 | \& ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
445 | \& Localtime([time]); | |
446 | .Ve | |
447 | .PP | |
448 | .Vb 2 | |
449 | \& Mktime | |
450 | \& $time = Mktime($year,$month,$day, $hour,$min,$sec); | |
451 | .Ve | |
452 | .PP | |
453 | .Vb 2 | |
454 | \& Timezone | |
455 | \& ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]); | |
456 | .Ve | |
457 | .PP | |
458 | .Vb 2 | |
459 | \& Date_to_Time | |
460 | \& $time = Date_to_Time($year,$month,$day, $hour,$min,$sec); | |
461 | .Ve | |
462 | .PP | |
463 | .Vb 2 | |
464 | \& Time_to_Date | |
465 | \& ($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]); | |
466 | .Ve | |
467 | .PP | |
468 | .Vb 2 | |
469 | \& Easter_Sunday | |
470 | \& ($year,$month,$day) = Easter_Sunday($year); | |
471 | .Ve | |
472 | .PP | |
473 | .Vb 2 | |
474 | \& Decode_Month | |
475 | \& if ($month = Decode_Month($string)) | |
476 | .Ve | |
477 | .PP | |
478 | .Vb 2 | |
479 | \& Decode_Day_of_Week | |
480 | \& if ($dow = Decode_Day_of_Week($string)) | |
481 | .Ve | |
482 | .PP | |
483 | .Vb 2 | |
484 | \& Decode_Language | |
485 | \& if ($lang = Decode_Language($string)) | |
486 | .Ve | |
487 | .PP | |
488 | .Vb 2 | |
489 | \& Decode_Date_EU | |
490 | \& if (($year,$month,$day) = Decode_Date_EU($string)) | |
491 | .Ve | |
492 | .PP | |
493 | .Vb 2 | |
494 | \& Decode_Date_US | |
495 | \& if (($year,$month,$day) = Decode_Date_US($string)) | |
496 | .Ve | |
497 | .PP | |
498 | .Vb 2 | |
499 | \& Fixed_Window | |
500 | \& $year = Fixed_Window($yy); | |
501 | .Ve | |
502 | .PP | |
503 | .Vb 2 | |
504 | \& Moving_Window | |
505 | \& $year = Moving_Window($yy); | |
506 | .Ve | |
507 | .PP | |
508 | .Vb 2 | |
509 | \& Compress | |
510 | \& $date = Compress($year,$month,$day); | |
511 | .Ve | |
512 | .PP | |
513 | .Vb 2 | |
514 | \& Uncompress | |
515 | \& if (($century,$year,$month,$day) = Uncompress($date)) | |
516 | .Ve | |
517 | .PP | |
518 | .Vb 2 | |
519 | \& check_compressed | |
520 | \& if (check_compressed($date)) | |
521 | .Ve | |
522 | .PP | |
523 | .Vb 2 | |
524 | \& Compressed_to_Text | |
525 | \& $string = Compressed_to_Text($date); | |
526 | .Ve | |
527 | .PP | |
528 | .Vb 2 | |
529 | \& Date_to_Text | |
530 | \& $string = Date_to_Text($year,$month,$day); | |
531 | .Ve | |
532 | .PP | |
533 | .Vb 2 | |
534 | \& Date_to_Text_Long | |
535 | \& $string = Date_to_Text_Long($year,$month,$day); | |
536 | .Ve | |
537 | .PP | |
538 | .Vb 2 | |
539 | \& English_Ordinal | |
540 | \& $string = English_Ordinal($number); | |
541 | .Ve | |
542 | .PP | |
543 | .Vb 2 | |
544 | \& Calendar | |
545 | \& $string = Calendar($year,$month[,$orthodox]); | |
546 | .Ve | |
547 | .PP | |
548 | .Vb 2 | |
549 | \& Month_to_Text | |
550 | \& $string = Month_to_Text($month); | |
551 | .Ve | |
552 | .PP | |
553 | .Vb 2 | |
554 | \& Day_of_Week_to_Text | |
555 | \& $string = Day_of_Week_to_Text($dow); | |
556 | .Ve | |
557 | .PP | |
558 | .Vb 2 | |
559 | \& Day_of_Week_Abbreviation | |
560 | \& $string = Day_of_Week_Abbreviation($dow); | |
561 | .Ve | |
562 | .PP | |
563 | .Vb 2 | |
564 | \& Language_to_Text | |
565 | \& $string = Language_to_Text($lang); | |
566 | .Ve | |
567 | .PP | |
568 | .Vb 4 | |
569 | \& Language | |
570 | \& $lang = Language(); | |
571 | \& Language($lang); | |
572 | \& $oldlang = Language($newlang); | |
573 | .Ve | |
574 | .PP | |
575 | .Vb 2 | |
576 | \& Languages | |
577 | \& $max_lang = Languages(); | |
578 | .Ve | |
579 | .PP | |
580 | .Vb 2 | |
581 | \& Decode_Date_EU2 | |
582 | \& if (($year,$month,$day) = Decode_Date_EU2($string)) | |
583 | .Ve | |
584 | .PP | |
585 | .Vb 2 | |
586 | \& Decode_Date_US2 | |
587 | \& if (($year,$month,$day) = Decode_Date_US2($string)) | |
588 | .Ve | |
589 | .PP | |
590 | .Vb 2 | |
591 | \& Parse_Date | |
592 | \& if (($year,$month,$day) = Parse_Date($string)) | |
593 | .Ve | |
594 | .PP | |
595 | .Vb 2 | |
596 | \& ISO_LC | |
597 | \& $lower = ISO_LC($string); | |
598 | .Ve | |
599 | .PP | |
600 | .Vb 2 | |
601 | \& ISO_UC | |
602 | \& $upper = ISO_UC($string); | |
603 | .Ve | |
604 | .PP | |
605 | .Vb 2 | |
606 | \& Version | |
607 | \& $string = Date::Calc::Version(); | |
608 | .Ve | |
609 | .SH "IMPORTANT NOTES" | |
610 | .IX Header "IMPORTANT NOTES" | |
611 | (See the section \*(L"\s-1RECIPES\s0\*(R" at the bottom of this document for | |
612 | solutions to common problems!) | |
613 | .IP "\(bu" 2 | |
614 | \&\*(L"Year 2000\*(R" (\*(L"Y2K\*(R") compliance | |
615 | .Sp | |
616 | The upper limit for any year number in this module is only given | |
617 | by the size of the largest positive integer that can be represented | |
618 | in a variable of the C type \*(L"int\*(R" on your system, which is at least | |
619 | 32767, according to the \s-1ANSI\s0 C standard (exceptions see below). | |
620 | .Sp | |
621 | In order to simplify calculations, this module projects the gregorian | |
622 | calendar back until the year 1\ A.D. \*(-- i.e., back \fB\s-1BEYOND\s0\fR the | |
623 | year 1582 when this calendar was first decreed by the Catholic Pope | |
624 | Gregory\ \s-1XIII\s0! | |
625 | .Sp | |
626 | Therefore, \fB\s-1BE\s0 \s-1SURE\s0 \s-1TO\s0 \s-1ALWAYS\s0 \s-1SPECIFY\s0 \*(L"1998\*(R" \s-1WHEN\s0 \s-1YOU\s0 \s-1MEAN\s0 \*(L"1998\*(R"\fR, | |
627 | for instance, and \fB\s-1DO\s0 \s-1NOT\s0 \s-1WRITE\s0 \*(L"98\*(R" \s-1INSTEAD\s0\fR, because this will | |
628 | in fact perform a calculation based on the year \*(L"98\*(R" A.D. and | |
629 | \&\fB\s-1NOT\s0\fR \*(L"1998\*(R"! | |
630 | .Sp | |
631 | An exception from this rule are the functions which contain the | |
632 | word \*(L"compress\*(R" in their names (which can only handle years between | |
633 | 1970 and 2069 and also accept the abbreviations \*(L"00\*(R" to \*(L"99\*(R"), and | |
634 | the functions whose names begin with \*(L"Decode_Date_\*(R" (which translate | |
635 | year numbers below 100 using a technique known as \*(L"moving window\*(R"). | |
636 | .Sp | |
637 | If you want to convert a two-digit year number into a full\-fledged, | |
638 | four-digit (at least for some years to come \f(CW\*(C`;\-)\*(C'\fR) year number, | |
639 | use the two functions \*(L"\fIFixed_Window()\fR\*(R" and \*(L"\fIMoving_Window()\fR\*(R" | |
640 | (see their description further below). | |
641 | .Sp | |
642 | Note also that the following import/export functions (which are | |
643 | interfaces to the \s-1POSIX\s0 functions \*(L"\fItime()\fR\*(R", \*(L"\fIgmtime()\fR\*(R", \*(L"\fIlocaltime()\fR\*(R" | |
644 | and \*(L"\fImktime()\fR\*(R" or (the last two) substitutes for the \s-1BSD\s0 function | |
645 | \&\*(L"\fItimegm()\fR\*(R" and the \s-1POSIX\s0 function \*(L"\fIgmtime()\fR\*(R") have a very limited | |
646 | range of representable dates (in contrast to all other functions | |
647 | in this package, which cover virtually any date including and | |
648 | after January\ 1st\ 1\ A.D.): | |
649 | .Sp | |
650 | .Vb 11 | |
651 | \& System_Clock() | |
652 | \& Today() | |
653 | \& Now() | |
654 | \& Today_and_Now() | |
655 | \& This_Year() | |
656 | \& Gmtime() | |
657 | \& Localtime() | |
658 | \& Mktime() | |
659 | \& Timezone() | |
660 | \& Date_to_Time() | |
661 | \& Time_to_Date() | |
662 | .Ve | |
663 | .Sp | |
664 | These functions can only deal with dates in the range from | |
665 | 01\-Jan\-1970\ 00:00:00\ \s-1GMT\s0 to 19\-Jan\-2038\ 03:14:07\ \s-1GMT\s0 | |
666 | (the latter limit is only authoritative on 32\ bit systems, | |
667 | however, and can (in principle, through a few code changes) | |
668 | be extended somewhat \f(CW\*(C`:\-)\*(C'\fR on 64\ bit systems). | |
669 | .Sp | |
670 | On MacOS Classic, the valid range of dates is between | |
671 | (both included) 01\-Jan\-1904\ 00:00:00 (local time) | |
672 | to 06\-Feb\-2040\ 06:28:15 (local time). | |
673 | .Sp | |
674 | Note further that the function \*(L"\fIEaster_Sunday()\fR\*(R" can only | |
675 | be used for years in the range 1583 to 2299. | |
676 | .IP "\(bu" 2 | |
677 | First index | |
678 | .Sp | |
679 | \&\fB\s-1ALL\s0\fR ranges in this module start with "\f(CW1\fR", \fB\s-1NOT\s0\fR "\f(CW0\fR"! | |
680 | .Sp | |
681 | I.e., the day of month, day of week, day of year, month of year, | |
682 | week of year, first valid year number and language \fB\s-1ALL\s0\fR start | |
683 | counting at one, \fB\s-1NOT\s0\fR zero! | |
684 | .Sp | |
685 | The only exception is the function "\f(CW\*(C`Week_Number()\*(C'\fR\*(L", which may | |
686 | in fact return \*(R"\f(CW0\fR" when the given date actually lies in the | |
687 | last week of the \fB\s-1PREVIOUS\s0\fR year, and of course the numbers for | |
688 | hours (\f(CW0..23\fR), minutes (\f(CW0..59\fR) and seconds (\f(CW0..59\fR). | |
689 | .IP "\(bu" 2 | |
690 | Function naming conventions | |
691 | .Sp | |
692 | Function names completely in lower case indicate a boolean return value. | |
693 | .IP "\(bu" 2 | |
694 | Boolean values | |
695 | .Sp | |
696 | Boolean values in this module are always a numeric zero ("\f(CW0\fR\*(L") for | |
697 | \&\*(R"false\*(L" and a numeric one (\*(R"\f(CW1\fR\*(L") for \*(R"true". | |
698 | .IP "\(bu" 2 | |
699 | Exception handling | |
700 | .Sp | |
701 | The functions in this module will usually die with a corresponding error | |
702 | message if their input parameters, intermediate results or output values | |
703 | are out of range. | |
704 | .Sp | |
705 | The following functions handle errors differently: | |
706 | .Sp | |
707 | .Vb 4 | |
708 | \& - check_date() | |
709 | \& - check_time() | |
710 | \& - check_business_date() | |
711 | \& - check_compressed() | |
712 | .Ve | |
713 | .Sp | |
714 | (which return a \*(L"false\*(R" return value when the given input does not represent | |
715 | a valid date or time), | |
716 | .Sp | |
717 | .Vb 1 | |
718 | \& - Nth_Weekday_of_Month_Year() | |
719 | .Ve | |
720 | .Sp | |
721 | (which returns an empty list if the requested 5th day of week does not exist), | |
722 | .Sp | |
723 | .Vb 6 | |
724 | \& - Decode_Month() | |
725 | \& - Decode_Day_of_Week() | |
726 | \& - Decode_Language() | |
727 | \& - Fixed_Window() | |
728 | \& - Moving_Window() | |
729 | \& - Compress() | |
730 | .Ve | |
731 | .Sp | |
732 | (which return "\f(CW0\fR" upon failure or invalid input), and | |
733 | .Sp | |
734 | .Vb 6 | |
735 | \& - Decode_Date_EU() | |
736 | \& - Decode_Date_US() | |
737 | \& - Decode_Date_EU2() | |
738 | \& - Decode_Date_US2() | |
739 | \& - Parse_Date() | |
740 | \& - Uncompress() | |
741 | .Ve | |
742 | .Sp | |
743 | (which return an empty list upon failure or invalid input). | |
744 | .Sp | |
745 | Note that you can always catch an exception thrown by any of the functions | |
746 | in this module and handle it yourself by enclosing the function call in an | |
747 | "\f(CW\*(C`eval\*(C'\fR\*(L" with curly brackets and checking the special variable \*(R"\f(CW$@\fR" | |
748 | (see \*(L"eval\*(R" in \fIperlfunc\fR\|(1) for details). | |
749 | .SH "DESCRIPTION" | |
750 | .IX Header "DESCRIPTION" | |
751 | .IP "\(bu" 2 | |
752 | \&\f(CW\*(C`use Date::Calc qw( Days_in_Year Days_in_Month ... );\*(C'\fR | |
753 | .IP "\(bu" 2 | |
754 | \&\f(CW\*(C`use Date::Calc qw(:all);\*(C'\fR | |
755 | .Sp | |
756 | You can either specify the functions you want to import explicitly by | |
757 | enumerating them between the parentheses of the "\f(CW\*(C`qw()\*(C'\fR\*(L" operator, or | |
758 | you can use the \*(R"\f(CW\*(C`:all\*(C'\fR" tag instead to import \fB\s-1ALL\s0\fR available functions. | |
759 | .IP "\(bu" 2 | |
760 | \&\f(CW\*(C`$days = Days_in_Year($year,$month);\*(C'\fR | |
761 | .Sp | |
762 | This function returns the sum of the number of days in the months starting | |
763 | with January up to and including "\f(CW$month\fR\*(L" in the given year \*(R"\f(CW$year\fR". | |
764 | .Sp | |
765 | I.e., "\f(CW\*(C`Days_in_Year(1998,1)\*(C'\fR\*(L" returns \*(R"\f(CW31\fR\*(L", \*(R"\f(CW\*(C`Days_in_Year(1998,2)\*(C'\fR\*(L" | |
766 | returns \*(R"\f(CW59\fR\*(L", \*(R"\f(CW\*(C`Days_in_Year(1998,3)\*(C'\fR\*(L" returns \*(R"\f(CW90\fR", and so on. | |
767 | .Sp | |
768 | Note that "\f(CW\*(C`Days_in_Year($year,12)\*(C'\fR\*(L" returns the number of days in the | |
769 | given year \*(R"\f(CW$year\fR\*(L", i.e., either \*(R"\f(CW365\fR\*(L" or \*(R"\f(CW366\fR". | |
770 | .IP "\(bu" 2 | |
771 | \&\f(CW\*(C`$days = Days_in_Month($year,$month);\*(C'\fR | |
772 | .Sp | |
773 | This function returns the number of days in the given month "\f(CW$month\fR\*(L" of | |
774 | the given year \*(R"\f(CW$year\fR". | |
775 | .Sp | |
776 | The year must always be supplied, even though it is only needed when the | |
777 | month is February, in order to determine whether it is a leap year or not. | |
778 | .Sp | |
779 | I.e., "\f(CW\*(C`Days_in_Month(1998,1)\*(C'\fR\*(L" returns \*(R"\f(CW31\fR\*(L", \*(R"\f(CW\*(C`Days_in_Month(1998,2)\*(C'\fR\*(L" | |
780 | returns \*(R"\f(CW28\fR\*(L", \*(R"\f(CW\*(C`Days_in_Month(2000,2)\*(C'\fR\*(L" returns \*(R"\f(CW29\fR\*(L", | |
781 | \&\*(R"\f(CW\*(C`Days_in_Month(1998,3)\*(C'\fR\*(L" returns \*(R"\f(CW31\fR", and so on. | |
782 | .IP "\(bu" 2 | |
783 | \&\f(CW\*(C`$weeks = Weeks_in_Year($year);\*(C'\fR | |
784 | .Sp | |
785 | This function returns the number of weeks in the given year "\f(CW$year\fR\*(L", | |
786 | i.e., either \*(R"\f(CW52\fR\*(L" or \*(R"\f(CW53\fR". | |
787 | .IP "\(bu" 2 | |
788 | \&\f(CW\*(C`if (leap_year($year))\*(C'\fR | |
789 | .Sp | |
790 | This function returns \*(L"true\*(R" ("\f(CW1\fR\*(L") if the given year \*(R"\f(CW$year\fR\*(L" is | |
791 | a leap year and \*(R"false\*(L" (\*(R"\f(CW0\fR") otherwise. | |
792 | .IP "\(bu" 2 | |
793 | \&\f(CW\*(C`if (check_date($year,$month,$day))\*(C'\fR | |
794 | .Sp | |
795 | This function returns \*(L"true\*(R" ("\f(CW1\fR\*(L") if the given three numerical | |
796 | values \*(R"\f(CW$year\fR\*(L", \*(R"\f(CW$month\fR\*(L" and \*(R"\f(CW$day\fR\*(L" constitute a valid date, | |
797 | and \*(R"false\*(L" (\*(R"\f(CW0\fR") otherwise. | |
798 | .IP "\(bu" 2 | |
799 | \&\f(CW\*(C`if (check_time($hour,$min,$sec))\*(C'\fR | |
800 | .Sp | |
801 | This function returns \*(L"true\*(R" ("\f(CW1\fR\*(L") if the given three numerical | |
802 | values \*(R"\f(CW$hour\fR\*(L", \*(R"\f(CW$min\fR\*(L" and \*(R"\f(CW$sec\fR" constitute a valid time | |
803 | (\f(CW\*(C`0 <= $hour < 24\*(C'\fR, \f(CW\*(C`0 <= $min < 60\*(C'\fR and | |
804 | \&\f(CW\*(C`0 <= $sec < 60\*(C'\fR), and \*(L"false\*(R" ("\f(CW0\fR") otherwise. | |
805 | .IP "\(bu" 2 | |
806 | \&\f(CW\*(C`if (check_business_date($year,$week,$dow))\*(C'\fR | |
807 | .Sp | |
808 | This function returns \*(L"true\*(R" ("\f(CW1\fR\*(L") if the given three numerical | |
809 | values \*(R"\f(CW$year\fR\*(L", \*(R"\f(CW$week\fR\*(L" and \*(R"\f(CW$dow\fR\*(L" constitute a valid date | |
810 | in business format, and \*(R"false\*(L" (\*(R"\f(CW0\fR") otherwise. | |
811 | .Sp | |
812 | \&\fBBeware\fR that this function does \fB\s-1NOT\s0\fR compute whether a given date | |
813 | is a business day (i.e., Monday to Friday)! | |
814 | .Sp | |
815 | To do so, use "\f(CW\*(C`(Day_of_Week($year,$month,$day) < 6)\*(C'\fR" instead. | |
816 | .IP "\(bu" 2 | |
817 | \&\f(CW\*(C`$doy = Day_of_Year($year,$month,$day);\*(C'\fR | |
818 | .Sp | |
819 | This function returns the (relative) number of the day of the given date | |
820 | in the given year. | |
821 | .Sp | |
822 | E.g., "\f(CW\*(C`Day_of_Year($year,1,1)\*(C'\fR\*(L" returns \*(R"\f(CW1\fR\*(L", | |
823 | \&\*(R"\f(CW\*(C`Day_of_Year($year,2,1)\*(C'\fR\*(L" returns \*(R"\f(CW32\fR\*(L", and | |
824 | \&\*(R"\f(CW\*(C`Day_of_Year($year,12,31)\*(C'\fR\*(L" returns either \*(R"\f(CW365\fR\*(L" or \*(R"\f(CW366\fR". | |
825 | .IP "\(bu" 2 | |
826 | \&\f(CW\*(C`$days = Date_to_Days($year,$month,$day);\*(C'\fR | |
827 | .Sp | |
828 | This function returns the (absolute) number of the day of the given date, | |
829 | where counting starts at the 1st of January of the year 1\ A.D. | |
830 | .Sp | |
831 | I.e., "\f(CW\*(C`Date_to_Days(1,1,1)\*(C'\fR\*(L" returns \*(R"\f(CW1\fR\*(L", \*(R"\f(CW\*(C`Date_to_Days(1,12,31)\*(C'\fR\*(L" | |
832 | returns \*(R"\f(CW365\fR\*(L", \*(R"\f(CW\*(C`Date_to_Days(2,1,1)\*(C'\fR\*(L" returns \*(R"\f(CW366\fR\*(L", | |
833 | \&\*(R"\f(CW\*(C`Date_to_Days(1998,5,1)\*(C'\fR\*(L" returns \*(R"\f(CW729510\fR", and so on. | |
834 | .Sp | |
835 | This is sometimes also referred to (not quite correctly) as the Julian | |
836 | date (or day). This may cause confusion, because also the number of the | |
837 | day in a year (from 1 to 365 or 366) is frequently called the \*(L"Julian date\*(R". | |
838 | .Sp | |
839 | In fact the calendar that was used \fB\s-1BEFORE\s0\fR the Gregorian calendar | |
840 | was the Julian calendar \- named after famous Julius Caesar, who had | |
841 | instituted it in Roman times. The Julian calendar was less precise | |
842 | because it had too many leap years compared to the true mean length | |
843 | of a year, and because rulers often changed it arbitrarily, in order | |
844 | to lengthen their own reign, for instance. | |
845 | .Sp | |
846 | In order to convert the number returned by this function back into | |
847 | a date, use the function "\f(CW\*(C`Add_Delta_Days()\*(C'\fR" (described further | |
848 | below), as follows: | |
849 | .Sp | |
850 | .Vb 2 | |
851 | \& $days = Date_to_Days($year,$month,$day); | |
852 | \& ($year,$month,$day) = Add_Delta_Days(1,1,1, $days - 1); | |
853 | .Ve | |
854 | .IP "\(bu" 2 | |
855 | \&\f(CW\*(C`$dow = Day_of_Week($year,$month,$day);\*(C'\fR | |
856 | .Sp | |
857 | This function returns the number of the day of week of the given date. | |
858 | .Sp | |
859 | The function returns "\f(CW1\fR\*(L" for Monday, \*(R"\f(CW2\fR\*(L" for Tuesday and so on | |
860 | until \*(R"\f(CW7\fR" for Sunday. | |
861 | .Sp | |
862 | Note that in the Hebrew calendar (on which the Christian calendar is based), | |
863 | the week starts with Sunday and ends with the Sabbath or Saturday (where | |
864 | according to the Genesis (as described in the Bible) the Lord rested from | |
865 | creating the world). | |
866 | .Sp | |
867 | In medieval times, Catholic Popes have decreed the Sunday to be the official | |
868 | day of rest, in order to dissociate the Christian from the Hebrew belief. | |
869 | .Sp | |
870 | Nowadays, the Sunday \fB\s-1AND\s0\fR the Saturday are commonly considered (and | |
871 | used as) days of rest, usually referred to as the \*(L"week\-end\*(R". | |
872 | .Sp | |
873 | Consistent with this practice, current norms and standards (such as | |
874 | \&\s-1ISO/R\s0\ 2015\-1971, \s-1DIN\s0\ 1355 and \s-1ISO\s0\ 8601) define the Monday | |
875 | as the first day of the week. | |
876 | .IP "\(bu" 2 | |
877 | \&\f(CW\*(C`$week = Week_Number($year,$month,$day);\*(C'\fR | |
878 | .Sp | |
879 | This function returns the number of the week the given date lies in. | |
880 | .Sp | |
881 | If the given date lies in the \fB\s-1LAST\s0\fR week of the \fB\s-1PREVIOUS\s0\fR year, | |
882 | "\f(CW0\fR" is returned. | |
883 | .Sp | |
884 | If the given date lies in the \fB\s-1FIRST\s0\fR week of the \fB\s-1NEXT\s0\fR year, | |
885 | "\f(CW\*(C`Weeks_in_Year($year) + 1\*(C'\fR" is returned. | |
886 | .IP "\(bu" 2 | |
887 | \&\f(CW\*(C`($week,$year) = Week_of_Year($year,$month,$day);\*(C'\fR | |
888 | .Sp | |
889 | This function returns the number of the week the given date lies in, | |
890 | as well as the year that week belongs to. | |
891 | .Sp | |
892 | I.e., if the given date lies in the \fB\s-1LAST\s0\fR week of the \fB\s-1PREVIOUS\s0\fR year, | |
893 | "\f(CW\*(C`(Weeks_in_Year($year\-1), $year\-1)\*(C'\fR" is returned. | |
894 | .Sp | |
895 | If the given date lies in the \fB\s-1FIRST\s0\fR week of the \fB\s-1NEXT\s0\fR year, | |
896 | "\f(CW\*(C`(1, $year+1)\*(C'\fR" is returned. | |
897 | .Sp | |
898 | Otherwise, "\f(CW\*(C`(Week_Number($year,$month,$day), $year)\*(C'\fR" is returned. | |
899 | .IP "\(bu" 2 | |
900 | \&\f(CW\*(C`$week = Week_of_Year($year,$month,$day);\*(C'\fR | |
901 | .Sp | |
902 | In scalar context, this function returns just the week number. This | |
903 | allows you to write "\f(CW\*(C`$week = Week_of_Year($year,$month,$day);\*(C'\fR\*(L" | |
904 | instead of \*(R"\f(CW\*(C`($week) = Week_of_Year($year,$month,$day);\*(C'\fR\*(L" (note | |
905 | the parentheses around \*(R"\f(CW$week\fR"). | |
906 | .Sp | |
907 | If the given date lies in the \fB\s-1LAST\s0\fR week of the \fB\s-1PREVIOUS\s0\fR year, | |
908 | "\f(CW\*(C`Weeks_in_Year($year\-1)\*(C'\fR" is returned. | |
909 | .Sp | |
910 | If the given date lies in the \fB\s-1FIRST\s0\fR week of the \fB\s-1NEXT\s0\fR year, | |
911 | "\f(CW1\fR" is returned. | |
912 | .Sp | |
913 | Otherwise the return value is identical with that of | |
914 | "\f(CW\*(C`Week_Number($year,$month,$day)\*(C'\fR". | |
915 | .Sp | |
916 | \&\fB\s-1BEWARE\s0\fR that using this function in scalar context is a \fB\s-1DANGEROUS\s0\fR | |
917 | feature, because without knowing which year the week belongs to, you | |
918 | might inadvertently assume the wrong one! | |
919 | .Sp | |
920 | If for instance you are iterating through an interval of dates, you might | |
921 | assume that the week always belongs to the same year as the given date, | |
922 | which unfortunately is \fB\s-1WRONG\s0\fR in some cases! | |
923 | .Sp | |
924 | In many years, the 31st of December for instance belongs to week number | |
925 | one of the \fB\s-1FOLLOWING\s0\fR year. Assuming that the year is the same as your | |
926 | date (31st of December, in this example), sends you back to the first week | |
927 | of the \fB\s-1CURRENT\s0\fR year \- the Monday of which, by the way, in case of bad | |
928 | luck, might actually lie in the year \fB\s-1BEFORE\s0\fR the current year! | |
929 | .Sp | |
930 | This actually happens in 2002, for example. | |
931 | .Sp | |
932 | So you always need to provide the correct corresponding year number | |
933 | by other means, keeping track of it yourself. | |
934 | .Sp | |
935 | In case you do not understand this, never mind, but then simply | |
936 | \&\fB\s-1DO\s0 \s-1NOT\s0 \s-1USE\s0\fR this function in scalar context! | |
937 | .IP "\(bu" 2 | |
938 | \&\f(CW\*(C`($year,$month,$day) = Monday_of_Week($week,$year);\*(C'\fR | |
939 | .Sp | |
940 | This function returns the date of the first day of the given week, i.e., | |
941 | the Monday. | |
942 | .Sp | |
943 | "\f(CW$year\fR\*(L" must be greater than or equal to \*(R"\f(CW1\fR\*(L", and \*(R"\f(CW$week\fR\*(L" must | |
944 | lie in the range \*(R"\f(CW1\fR\*(L" to \*(R"\f(CW\*(C`Weeks_in_Year($year)\*(C'\fR". | |
945 | .Sp | |
946 | Note that you can write | |
947 | "\f(CW\*(C`($year,$month,$day) = Monday_of_Week(Week_of_Year($year,$month,$day));\*(C'\fR" | |
948 | in order to calculate the date of the Monday of the same week as the | |
949 | given date. | |
950 | .Sp | |
951 | If you want to calculate any other day of week in the same week as a | |
952 | given date, use | |
953 | .Sp | |
954 | .Vb 1 | |
955 | \& @date = Add_Delta_Days(Monday_of_Week(Week_of_Year(@date)),$offset); | |
956 | .Ve | |
957 | .Sp | |
958 | where \f(CW\*(C`$offset = 1\*(C'\fR for Tuesday, \f(CW2\fR for Wednesday etc. | |
959 | .IP "\(bu" 2 | |
960 | \&\f(CW\*(C`if (($year,$month,$day) = Nth_Weekday_of_Month_Year($year,$month,$dow,$n))\*(C'\fR | |
961 | .Sp | |
962 | This function calculates the date of the "\f(CW$n\fR\*(L"th day of week \*(R"\f(CW$dow\fR\*(L" | |
963 | in the given month \*(R"\f(CW$month\fR\*(L" and year \*(R"\f(CW$year\fR"; such as, for example, | |
964 | the 3rd Thursday of a given month and year. | |
965 | .Sp | |
966 | This can be used to send a notification mail to the members of a group | |
967 | which meets regularly on every 3rd Thursday of a month, for instance. | |
968 | .Sp | |
969 | (See the section \*(L"\s-1RECIPES\s0\*(R" near the end of this document for a code | |
970 | snippet to actually do so.) | |
971 | .Sp | |
972 | "\f(CW$year\fR\*(L" must be greater than or equal to \*(R"\f(CW1\fR\*(L", \*(R"\f(CW$month\fR\*(L" must lie | |
973 | in the range \*(R"\f(CW1\fR\*(L" to \*(R"\f(CW12\fR\*(L", \*(R"\f(CW$dow\fR\*(L" must lie in the range \*(R"\f(CW1\fR\*(L" | |
974 | to \*(R"\f(CW7\fR\*(L" and \*(R"\f(CW$n\fR\*(L" must lie in the range \*(R"\f(CW1\fR\*(L" to \*(R"\f(CW5\fR", or a fatal | |
975 | error (with appropriate error message) occurs. | |
976 | .Sp | |
977 | The function returns an empty list when the 5th of a given day of week | |
978 | does not exist in the given month and year. | |
979 | .IP "\(bu" 2 | |
980 | \&\f(CW\*(C`($year,$week,$dow) = Standard_to_Business($year,$month,$day);\*(C'\fR | |
981 | .Sp | |
982 | This function converts a given date from standard notation (year, | |
983 | month, day (of month)) to business notation (year, week, day of week). | |
984 | .IP "\(bu" 2 | |
985 | \&\f(CW\*(C`($year,$month,$day) = Business_to_Standard($year,$week,$dow);\*(C'\fR | |
986 | .Sp | |
987 | This function converts a given date from business notation (year, | |
988 | week, day of week) to standard notation (year, month, day (of month)). | |
989 | .IP "\(bu" 2 | |
990 | \&\f(CW\*(C`$Dd = Delta_Days($year1,$month1,$day1, $year2,$month2,$day2);\*(C'\fR | |
991 | .Sp | |
992 | This function returns the difference in days between the two given | |
993 | dates. | |
994 | .Sp | |
995 | The result is positive if the two dates are in chronological order, | |
996 | i.e., if date #1 comes chronologically \fB\s-1BEFORE\s0\fR date #2, and negative | |
997 | if the order of the two dates is reversed. | |
998 | .Sp | |
999 | The result is zero if the two dates are identical. | |
1000 | .IP "\(bu" 2 | |
1001 | \&\f(CW\*(C`($Dd,$Dh,$Dm,$Ds) = Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);\*(C'\fR | |
1002 | .Sp | |
1003 | This function returns the difference in days, hours, minutes and seconds | |
1004 | between the two given dates with times. | |
1005 | .Sp | |
1006 | All four return values will be positive if the two dates are in chronological | |
1007 | order, i.e., if date #1 comes chronologically \fB\s-1BEFORE\s0\fR date #2, and negative | |
1008 | (in all four return values!) if the order of the two dates is reversed. | |
1009 | .Sp | |
1010 | This is so that the two functions "\f(CW\*(C`Delta_DHMS()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`Add_Delta_DHMS()\*(C'\fR" | |
1011 | (description see further below) are complementary, i.e., mutually inverse: | |
1012 | .Sp | |
1013 | .Vb 1 | |
1014 | \& Add_Delta_DHMS(@date1,@time1, Delta_DHMS(@date1,@time1, @date2,@time2)) | |
1015 | .Ve | |
1016 | .Sp | |
1017 | yields "\f(CW\*(C`(@date2,@time2)\*(C'\fR" again, whereas | |
1018 | .Sp | |
1019 | .Vb 2 | |
1020 | \& Add_Delta_DHMS(@date2,@time2, | |
1021 | \& map(-$_, Delta_DHMS(@date1,@time1, @date2,@time2))) | |
1022 | .Ve | |
1023 | .Sp | |
1024 | yields "\f(CW\*(C`(@date1,@time1)\*(C'\fR", and | |
1025 | .Sp | |
1026 | .Vb 1 | |
1027 | \& Delta_DHMS(@date1,@time1, Add_Delta_DHMS(@date1,@time1, @delta)) | |
1028 | .Ve | |
1029 | .Sp | |
1030 | yields "\f(CW@delta\fR" again. | |
1031 | .Sp | |
1032 | The result is zero (in all four return values) if the two dates and times | |
1033 | are identical. | |
1034 | .IP "\(bu" 2 | |
1035 | \&\f(CW\*(C`($Dy,$Dm,$Dd) = Delta_YMD($year1,$month1,$day1, $year2,$month2,$day2);\*(C'\fR | |
1036 | .Sp | |
1037 | This function returns the vector | |
1038 | .Sp | |
1039 | .Vb 1 | |
1040 | \& ( $year2 - $year1, $month2 - $month1, $day2 - $day1 ) | |
1041 | .Ve | |
1042 | .Sp | |
1043 | An error occurs if any of the two dates is invalid. | |
1044 | .IP "\(bu" 2 | |
1045 | \&\f(CW\*(C`($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);\*(C'\fR | |
1046 | .Sp | |
1047 | This function is based on the function \*(L"\fIDelta_YMD()\fR\*(R" above but additionally | |
1048 | calculates the time difference. When a carry over from the time difference | |
1049 | occurs, the value of "\f(CW$D_d\fR" is adjusted accordingly, thus giving the | |
1050 | correct total date/time difference. | |
1051 | .Sp | |
1052 | Arguments are expected to be in chronological order to yield a (usually) | |
1053 | positive result. | |
1054 | .Sp | |
1055 | In any case, adding the result of this function to the first date/time value | |
1056 | (\f(CW\*(C`$year1,$month1,$day1,\*(C'\fR \f(CW\*(C`$hour1,$min1,$sec1\*(C'\fR) always gives the second | |
1057 | date/time value (\f(CW\*(C`$year2,$month2,$day2,\*(C'\fR \f(CW\*(C`$hour2,$min2,$sec2\*(C'\fR) again, | |
1058 | and adding the negative result (all elements of the result vector negated) | |
1059 | to the second date/time value gives the first date/time value. | |
1060 | .Sp | |
1061 | See the function \*(L"\fIAdd_Delta_YMDHMS()\fR\*(R" further below for adding a date/time | |
1062 | value and a date/time difference. | |
1063 | .Sp | |
1064 | An error occurs if any of the two date/time values is invalid. | |
1065 | .IP "\(bu" 2 | |
1066 | \&\f(CW\*(C`($Dd,$Dh,$Dm,$Ds) = Normalize_DHMS($Dd,$Dh,$Dm,$Ds);\*(C'\fR | |
1067 | .Sp | |
1068 | This function takes four arbitrary values for days, hours, minutes | |
1069 | and seconds (which may have different signs) and renormalizes them | |
1070 | so that the values for hours, minutes and seconds will lie in the | |
1071 | ranges \f(CW\*(C`[\-23..23]\*(C'\fR, \f(CW\*(C`[\-59..59]\*(C'\fR and \f(CW\*(C`[\-59..59]\*(C'\fR, respectively, | |
1072 | and so that all four values have the same sign (or are zero). | |
1073 | .Sp | |
1074 | The given values are left untouched, i.e., unchanged. | |
1075 | .IP "\(bu" 2 | |
1076 | \&\f(CW\*(C`($year,$month,$day) = Add_Delta_Days($year,$month,$day, $Dd);\*(C'\fR | |
1077 | .Sp | |
1078 | This function has two principal uses: | |
1079 | .Sp | |
1080 | First, it can be used to calculate a new date, given an initial date and | |
1081 | an offset (which may be positive or negative) in days, in order to answer | |
1082 | questions like \*(L"today plus 90 days \*(-- which date gives that?\*(R". | |
1083 | .Sp | |
1084 | (In order to add a weeks offset, simply multiply the weeks offset with | |
1085 | "\f(CW7\fR" and use that as your days offset.) | |
1086 | .Sp | |
1087 | Second, it can be used to convert the canonical representation of a date, | |
1088 | i.e., the number of that day (where counting starts at the 1st of January | |
1089 | in 1\ A.D.), back into a date given as year, month and day. | |
1090 | .Sp | |
1091 | Because counting starts at "\f(CW1\fR\*(L", you will actually have to subtract \*(R"\f(CW1\fR" | |
1092 | from the canonical date in order to get back the original date: | |
1093 | .Sp | |
1094 | .Vb 1 | |
1095 | \& $canonical = Date_to_Days($year,$month,$day); | |
1096 | .Ve | |
1097 | .Sp | |
1098 | .Vb 1 | |
1099 | \& ($year,$month,$day) = Add_Delta_Days(1,1,1, $canonical - 1); | |
1100 | .Ve | |
1101 | .Sp | |
1102 | Moreover, this function is the inverse of the function "\f(CW\*(C`Delta_Days()\*(C'\fR": | |
1103 | .Sp | |
1104 | .Vb 1 | |
1105 | \& Add_Delta_Days(@date1, Delta_Days(@date1, @date2)) | |
1106 | .Ve | |
1107 | .Sp | |
1108 | yields "\f(CW@date2\fR" again, whereas | |
1109 | .Sp | |
1110 | .Vb 1 | |
1111 | \& Add_Delta_Days(@date2, -Delta_Days(@date1, @date2)) | |
1112 | .Ve | |
1113 | .Sp | |
1114 | yields "\f(CW@date1\fR", and | |
1115 | .Sp | |
1116 | .Vb 1 | |
1117 | \& Delta_Days(@date1, Add_Delta_Days(@date1, $delta)) | |
1118 | .Ve | |
1119 | .Sp | |
1120 | yields "\f(CW$delta\fR" again. | |
1121 | .IP "\(bu" 2 | |
1122 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec) = Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, $Dd,$Dh,$Dm,$Ds);\*(C'\fR | |
1123 | .Sp | |
1124 | This function serves to add a days, hours, minutes and seconds offset to a | |
1125 | given date and time, in order to answer questions like \*(L"today and now plus | |
1126 | 7 days but minus 5 hours and then plus 30 minutes, what date and time gives | |
1127 | that?\*(R": | |
1128 | .Sp | |
1129 | .Vb 1 | |
1130 | \& ($y,$m,$d,$H,$M,$S) = Add_Delta_DHMS(Today_and_Now(), +7,-5,+30,0); | |
1131 | .Ve | |
1132 | .IP "\(bu" 2 | |
1133 | \&\f(CW\*(C`($year,$month,$day) = Add_Delta_YM($year,$month,$day, $Dy,$Dm);\*(C'\fR | |
1134 | .Sp | |
1135 | This function can be used to add a year and/or month offset to a given | |
1136 | date. | |
1137 | .Sp | |
1138 | In contrast to the function described immediately below | |
1139 | ("\f(CW\*(C`Add_Delta_YMD()\*(C'\fR\*(L"), this function does no \*(R"wrapping" into | |
1140 | the next month if the day happens to lie outside the valid range | |
1141 | for the resulting year and month (after adding the year and month | |
1142 | offsets). Instead, it simply truncates the day to the last possible | |
1143 | day of the resulting month. | |
1144 | .Sp | |
1145 | Examples: | |
1146 | .Sp | |
1147 | Adding an offset of 0 years, 1 month to the date (1999,1,31) would result | |
1148 | in the (invalid) date (1999,2,31). The function replaces this result by | |
1149 | the (valid) date (1999,2,28). | |
1150 | .Sp | |
1151 | Adding an offset of 1 year, 1 month to the same date (1999,1,31) as above | |
1152 | would result in the (still invalid) date (2000,2,31). The function replaces | |
1153 | this result by the valid date (2000,2,29) (because 2000 is a leap year). | |
1154 | .Sp | |
1155 | Note that the year and month offsets can be negative, and that they can | |
1156 | have different signs. | |
1157 | .Sp | |
1158 | If you want to additionally add a days offset, use the function | |
1159 | "\f(CW\*(C`Add_Delta_Days()\*(C'\fR\*(L" before or after calling \*(R"\f(CW\*(C`Add_Delta_YM()\*(C'\fR": | |
1160 | .Sp | |
1161 | .Vb 2 | |
1162 | \& @date2 = Add_Delta_Days( Add_Delta_YM(@date1, $Dy,$Dm), $Dd ); | |
1163 | \& @date2 = Add_Delta_YM( Add_Delta_Days(@date1, $Dd), $Dy,$Dm ); | |
1164 | .Ve | |
1165 | .Sp | |
1166 | Note that your result may depend on the order in which you call | |
1167 | these two functions! | |
1168 | .Sp | |
1169 | Consider the date (1999,2,28) and the offsets 0 years, 1 month | |
1170 | and 1 day: | |
1171 | .Sp | |
1172 | (1999,2,28) plus one month is (1999,3,28), plus one day is | |
1173 | (1999,3,29). (1999,2,28) plus one day is (1999,3,1), plus | |
1174 | one month is (1999,4,1). | |
1175 | .Sp | |
1176 | (Which is also the reason why the "\f(CW\*(C`Add_Delta_YM()\*(C'\fR" function | |
1177 | does not allow to add a days offset, because this would actually | |
1178 | require \s-1TWO\s0 functions: One for adding the days offset \s-1BEFORE\s0 and | |
1179 | one for adding it \s-1AFTER\s0 applying the year/month offsets.) | |
1180 | .Sp | |
1181 | An error occurs if the initial date is not valid. | |
1182 | .Sp | |
1183 | Note that "\f(CW\*(C`Add_Delta_YM( Add_Delta_YM(@date, $Dy,$Dm), \-$Dy,\-$Dm );\*(C'\fR\*(L" | |
1184 | will not, in general, return the original date \*(R"\f(CW@date\fR" (consider | |
1185 | the examples given above!). | |
1186 | .IP "\(bu" 2 | |
1187 | \&\f(CW\*(C`($year,$month,$day) = Add_Delta_YMD($year,$month,$day, $Dy,$Dm,$Dd);\*(C'\fR | |
1188 | .Sp | |
1189 | This function serves to add a years, months and days offset to a given date. | |
1190 | .Sp | |
1191 | (In order to add a weeks offset, simply multiply the weeks offset with "\f(CW7\fR" | |
1192 | and add this number to your days offset.) | |
1193 | .Sp | |
1194 | Note that the three offsets for years, months and days are applied | |
1195 | independently from each other. This also allows them to have | |
1196 | different signs. | |
1197 | .Sp | |
1198 | The years and months offsets are applied first, and the days offset | |
1199 | is applied last. | |
1200 | .Sp | |
1201 | If the resulting date happens to fall on a day after the end of the | |
1202 | resulting month, like the 32nd of April or the 30th of February, then | |
1203 | the date is simply counted forward into the next month (possibly also | |
1204 | into the next year) by the number of excessive days (e.g., the 32nd of | |
1205 | April will become the 2nd of May). | |
1206 | .Sp | |
1207 | \&\fB\s-1BEWARE\s0\fR that this behaviour differs from that of previous versions | |
1208 | of this module! In previous versions, the day was simply truncated to | |
1209 | the maximum number of days in the resulting month. | |
1210 | .Sp | |
1211 | If you want the previous behaviour, use the new function "\f(CW\*(C`Add_Delta_YM()\*(C'\fR\*(L" | |
1212 | (described immediately above) plus the function \*(R"\f(CW\*(C`Add_Delta_Days()\*(C'\fR" | |
1213 | instead. | |
1214 | .Sp | |
1215 | \&\fB\s-1BEWARE\s0\fR also that because a year and a month offset is not equivalent | |
1216 | to a fixed number of days, the transformation performed by this function | |
1217 | is \fB\s-1NOT\s0 \s-1ALWAYS\s0 \s-1REVERSIBLE\s0\fR! | |
1218 | .Sp | |
1219 | This is in contrast to the functions "\f(CW\*(C`Add_Delta_Days()\*(C'\fR\*(L" and | |
1220 | \&\*(R"\f(CW\*(C`Add_Delta_DHMS()\*(C'\fR\*(L", which are fully and truly reversible (with | |
1221 | the help of the functions \*(R"\f(CW\*(C`Delta_Days()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`Delta_DHMS()\*(C'\fR", | |
1222 | for instance). | |
1223 | .Sp | |
1224 | Note that for this same reason, | |
1225 | .Sp | |
1226 | .Vb 2 | |
1227 | \& @date = Add_Delta_YMD( | |
1228 | \& Add_Delta_YMD(@date, $Dy,$Dm,$Dd), -$Dy,-$Dm,-$Dd); | |
1229 | .Ve | |
1230 | .Sp | |
1231 | will in general \fB\s-1NOT\s0\fR return the initial date "\f(CW@date\fR". | |
1232 | .Sp | |
1233 | Note that this is \fB\s-1NOT\s0\fR a program bug but \fB\s-1NECESSARILY\s0\fR so | |
1234 | because of the variable lengths of years and months! | |
1235 | .IP "\(bu" 2 | |
1236 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec) = Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, $D_y,$D_m,$D_d, $Dh,$Dm,$Ds);\*(C'\fR | |
1237 | .Sp | |
1238 | Same as the function above, except that a time offset may be given in | |
1239 | addition to the year, month and day offset. | |
1240 | .IP "\(bu" 2 | |
1241 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = System_Clock([$gmt]);\*(C'\fR | |
1242 | .Sp | |
1243 | If your operating system supports the corresponding system calls | |
1244 | ("\f(CW\*(C`time()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`localtime()\*(C'\fR\*(L" or \*(R"\f(CW\*(C`gmtime()\*(C'\fR"), this function | |
1245 | will return the information provided by your system clock, i.e., | |
1246 | the current date and time, the number of the day of year, the number | |
1247 | of the day of week and a flag signaling whether daylight savings time | |
1248 | is currently in effect or not. | |
1249 | .Sp | |
1250 | The ranges of values returned (and their meanings) are as follows: | |
1251 | .Sp | |
1252 | .Vb 2 | |
1253 | \& $year : 1970..2038 (or more) [Unix etc.] | |
1254 | \& $year : 1904..2040 [MacOS Classic] | |
1255 | .Ve | |
1256 | .Sp | |
1257 | .Vb 8 | |
1258 | \& $month : 1..12 | |
1259 | \& $day : 1..31 | |
1260 | \& $hour : 0..23 | |
1261 | \& $min : 0..59 | |
1262 | \& $sec : 0..59 (0..61 on some systems) | |
1263 | \& $doy : 1..366 | |
1264 | \& $dow : 1..7 | |
1265 | \& $dst : -1..1 | |
1266 | .Ve | |
1267 | .Sp | |
1268 | "\f(CW$doy\fR\*(L" is the day of year, sometimes also referred to as the | |
1269 | \&\*(R"julian date\*(L", which starts at \*(R"\f(CW1\fR" and goes up to the number | |
1270 | of days in that year. | |
1271 | .Sp | |
1272 | The day of week ("\f(CW$dow\fR\*(L") will be \*(R"\f(CW1\fR\*(L" for Monday, \*(R"\f(CW2\fR\*(L" for | |
1273 | Tuesday and so on until \*(R"\f(CW7\fR" for Sunday. | |
1274 | .Sp | |
1275 | The daylight savings time flag ("\f(CW$dst\fR\*(L") will be \*(R"\f(CW\*(C`\-1\*(C'\fR\*(L" if this | |
1276 | information is not available on your system, \*(R"\f(CW0\fR\*(L" for no daylight | |
1277 | savings time (i.e., winter time) and \*(R"\f(CW1\fR" when daylight savings | |
1278 | time is in effect. | |
1279 | .Sp | |
1280 | If your operating system does not provide the necessary system calls, | |
1281 | calling this function will result in a fatal \*(L"not available on this | |
1282 | system\*(R" error message. | |
1283 | .Sp | |
1284 | If you want to handle this exception yourself, use "\f(CW\*(C`eval\*(C'\fR" as follows: | |
1285 | .Sp | |
1286 | .Vb 2 | |
1287 | \& eval { ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
1288 | \& System_Clock(); }; | |
1289 | .Ve | |
1290 | .Sp | |
1291 | .Vb 5 | |
1292 | \& if ($@) | |
1293 | \& { | |
1294 | \& # Handle missing system clock | |
1295 | \& # (For instance, ask user to enter this information manually) | |
1296 | \& } | |
1297 | .Ve | |
1298 | .Sp | |
1299 | Note that curlies (\*(L"{\*(R" and \*(L"}\*(R") are used here to delimit the statement to | |
1300 | be \*(L"eval\*(R"ed (which is the way to catch exceptions in Perl), and not quotes | |
1301 | (which is a way to evaluate Perl expressions at runtime). | |
1302 | .Sp | |
1303 | If the optional (boolean) input parameter "\f(CW$gmt\fR\*(L" is given, a \*(R"true\*(L" | |
1304 | value (\*(R"\f(CW1\fR\*(L") will cause \*(R"\f(CW\*(C`gmtime()\*(C'\fR\*(L" to be used instead of \*(R"\f(CW\*(C`localtime()\*(C'\fR", | |
1305 | internally, thus returning Greenwich Mean Time (\s-1GMT\s0, or \s-1UTC\s0) instead of | |
1306 | local time. | |
1307 | .IP "\(bu" 2 | |
1308 | \&\f(CW\*(C`($year,$month,$day) = Today([$gmt]);\*(C'\fR | |
1309 | .Sp | |
1310 | This function returns a subset of the values returned by the function | |
1311 | "\f(CW\*(C`System_Clock()\*(C'\fR" (see above for details), namely the current year, | |
1312 | month and day. | |
1313 | .Sp | |
1314 | A fatal \*(L"not available on this system\*(R" error message will appear if the | |
1315 | corresponding system calls are not supported by your current operating | |
1316 | system. | |
1317 | .Sp | |
1318 | If the optional (boolean) input parameter "\f(CW$gmt\fR\*(L" is given, a \*(R"true\*(L" | |
1319 | value (\*(R"\f(CW1\fR\*(L") will cause \*(R"\f(CW\*(C`gmtime()\*(C'\fR\*(L" to be used instead of \*(R"\f(CW\*(C`localtime()\*(C'\fR", | |
1320 | internally, thus returning Greenwich Mean Time (\s-1GMT\s0, or \s-1UTC\s0) instead of | |
1321 | local time. | |
1322 | .IP "\(bu" 2 | |
1323 | \&\f(CW\*(C`($hour,$min,$sec) = Now([$gmt]);\*(C'\fR | |
1324 | .Sp | |
1325 | This function returns a subset of the values returned by the function | |
1326 | "\f(CW\*(C`System_Clock()\*(C'\fR" (see above for details), namely the current time | |
1327 | (hours, minutes and full seconds). | |
1328 | .Sp | |
1329 | A fatal \*(L"not available on this system\*(R" error message will appear if the | |
1330 | corresponding system calls are not supported by your current operating | |
1331 | system. | |
1332 | .Sp | |
1333 | If the optional (boolean) input parameter "\f(CW$gmt\fR\*(L" is given, a \*(R"true\*(L" | |
1334 | value (\*(R"\f(CW1\fR\*(L") will cause \*(R"\f(CW\*(C`gmtime()\*(C'\fR\*(L" to be used instead of \*(R"\f(CW\*(C`localtime()\*(C'\fR", | |
1335 | internally, thus returning Greenwich Mean Time (\s-1GMT\s0, or \s-1UTC\s0) instead of | |
1336 | local time. | |
1337 | .IP "\(bu" 2 | |
1338 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]);\*(C'\fR | |
1339 | .Sp | |
1340 | This function returns a subset of the values returned by the function | |
1341 | "\f(CW\*(C`System_Clock()\*(C'\fR" (see above for details), namely the current date | |
1342 | (year, month, day) and time (hours, minutes and full seconds). | |
1343 | .Sp | |
1344 | A fatal \*(L"not available on this system\*(R" error message will appear if the | |
1345 | corresponding system calls are not supported by your current operating | |
1346 | system. | |
1347 | .Sp | |
1348 | If the optional (boolean) input parameter "\f(CW$gmt\fR\*(L" is given, a \*(R"true\*(L" | |
1349 | value (\*(R"\f(CW1\fR\*(L") will cause \*(R"\f(CW\*(C`gmtime()\*(C'\fR\*(L" to be used instead of \*(R"\f(CW\*(C`localtime()\*(C'\fR", | |
1350 | internally, thus returning Greenwich Mean Time (\s-1GMT\s0, or \s-1UTC\s0) instead of | |
1351 | local time. | |
1352 | .IP "\(bu" 2 | |
1353 | \&\f(CW\*(C`$year = This_Year([$gmt]);\*(C'\fR | |
1354 | .Sp | |
1355 | This function returns the current year, according to local time. | |
1356 | .Sp | |
1357 | A fatal \*(L"not available on this system\*(R" error message will appear if the | |
1358 | corresponding system calls are not supported by your current operating | |
1359 | system. | |
1360 | .Sp | |
1361 | If the optional (boolean) input parameter "\f(CW$gmt\fR\*(L" is given, a \*(R"true\*(L" | |
1362 | value (\*(R"\f(CW1\fR\*(L") will cause \*(R"\f(CW\*(C`gmtime()\*(C'\fR\*(L" to be used instead of \*(R"\f(CW\*(C`localtime()\*(C'\fR", | |
1363 | internally, thus returning Greenwich Mean Time (\s-1GMT\s0, or \s-1UTC\s0) instead of | |
1364 | local time. However, this will only make a difference within a few hours | |
1365 | around New Year (unless you are on a Pacific island, where this can | |
1366 | be almost 24 hours). | |
1367 | .IP "\(bu" 2 | |
1368 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Gmtime([time]);\*(C'\fR | |
1369 | .Sp | |
1370 | This is Date::Calc's equivalent of Perl's built-in \*(L"\fIgmtime()\fR\*(R" function. | |
1371 | See also \*(L"gmtime\*(R" in perlfunc. | |
1372 | .Sp | |
1373 | The ranges of values returned (and their meanings) are as follows: | |
1374 | .Sp | |
1375 | .Vb 2 | |
1376 | \& $year : 1970..2038 (or more) [Unix etc.] | |
1377 | \& $year : 1904..2040 [MacOS Classic] | |
1378 | .Ve | |
1379 | .Sp | |
1380 | .Vb 8 | |
1381 | \& $month : 1..12 | |
1382 | \& $day : 1..31 | |
1383 | \& $hour : 0..23 | |
1384 | \& $min : 0..59 | |
1385 | \& $sec : 0..59 | |
1386 | \& $doy : 1..366 | |
1387 | \& $dow : 1..7 | |
1388 | \& $dst : -1..1 | |
1389 | .Ve | |
1390 | .Sp | |
1391 | "\f(CW$doy\fR\*(L" is the day of year, sometimes also referred to as the | |
1392 | \&\*(R"julian date\*(L", which starts at \*(R"\f(CW1\fR" and goes up to the number | |
1393 | of days in that year. | |
1394 | .Sp | |
1395 | The day of week ("\f(CW$dow\fR\*(L") will be \*(R"\f(CW1\fR\*(L" for Monday, \*(R"\f(CW2\fR\*(L" for | |
1396 | Tuesday and so on until \*(R"\f(CW7\fR" for Sunday. | |
1397 | .Sp | |
1398 | The daylight savings time flag ("\f(CW$dst\fR\*(L") will be \*(R"\f(CW\*(C`\-1\*(C'\fR\*(L" if this | |
1399 | information is not available on your system, \*(R"\f(CW0\fR\*(L" for no daylight | |
1400 | savings time (i.e., winter time) and \*(R"\f(CW1\fR" when daylight savings | |
1401 | time is in effect. | |
1402 | .Sp | |
1403 | A fatal \*(L"time out of range\*(R" error will occur if the given time value | |
1404 | is out of range \f(CW\*(C`[0..(~0>>1)]\*(C'\fR. | |
1405 | .Sp | |
1406 | If the time value is omitted, the \*(L"\fItime()\fR\*(R" function is called instead, | |
1407 | internally. | |
1408 | .IP "\(bu" 2 | |
1409 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Localtime([time]);\*(C'\fR | |
1410 | .Sp | |
1411 | This is Date::Calc's equivalent of Perl's built-in \*(L"\fIlocaltime()\fR\*(R" function. | |
1412 | See also \*(L"localtime\*(R" in perlfunc. | |
1413 | .Sp | |
1414 | The ranges of values returned (and their meanings) are as follows: | |
1415 | .Sp | |
1416 | .Vb 2 | |
1417 | \& $year : 1970..2038 (or more) [Unix etc.] | |
1418 | \& $year : 1904..2040 [MacOS Classic] | |
1419 | .Ve | |
1420 | .Sp | |
1421 | .Vb 8 | |
1422 | \& $month : 1..12 | |
1423 | \& $day : 1..31 | |
1424 | \& $hour : 0..23 | |
1425 | \& $min : 0..59 | |
1426 | \& $sec : 0..59 | |
1427 | \& $doy : 1..366 | |
1428 | \& $dow : 1..7 | |
1429 | \& $dst : -1..1 | |
1430 | .Ve | |
1431 | .Sp | |
1432 | "\f(CW$doy\fR\*(L" is the day of year, sometimes also referred to as the | |
1433 | \&\*(R"julian date\*(L", which starts at \*(R"\f(CW1\fR" and goes up to the number | |
1434 | of days in that year. | |
1435 | .Sp | |
1436 | The day of week ("\f(CW$dow\fR\*(L") will be \*(R"\f(CW1\fR\*(L" for Monday, \*(R"\f(CW2\fR\*(L" for | |
1437 | Tuesday and so on until \*(R"\f(CW7\fR" for Sunday. | |
1438 | .Sp | |
1439 | The daylight savings time flag ("\f(CW$dst\fR\*(L") will be \*(R"\f(CW\*(C`\-1\*(C'\fR\*(L" if this | |
1440 | information is not available on your system, \*(R"\f(CW0\fR\*(L" for no daylight | |
1441 | savings time (i.e., winter time) and \*(R"\f(CW1\fR" when daylight savings | |
1442 | time is in effect. | |
1443 | .Sp | |
1444 | A fatal \*(L"time out of range\*(R" error will occur if the given time value is | |
1445 | out of range \f(CW\*(C`[0..(~0>>1)]\*(C'\fR. | |
1446 | .Sp | |
1447 | If the time value is omitted, the \*(L"\fItime()\fR\*(R" function is called instead, | |
1448 | internally. | |
1449 | .IP "\(bu" 2 | |
1450 | \&\f(CW\*(C`$time = Mktime($year,$month,$day, $hour,$min,$sec);\*(C'\fR | |
1451 | .Sp | |
1452 | This function converts a date into a time value, i.e., into the number | |
1453 | of seconds since whatever moment in time your system considers to be | |
1454 | the \*(L"epoch\*(R". On Unix and most other systems this is the number of seconds | |
1455 | since January 1st 1970 at midnight (\s-1GMT\s0). On MacOS Classic this is the | |
1456 | number of seconds since January 1st 1904 at midnight (local time). | |
1457 | .Sp | |
1458 | The function is similar to the \*(L"\fIPOSIX::mktime()\fR\*(R" function (see \*(L"mktime\*(R" in \s-1POSIX\s0 | |
1459 | for more details), but in contrast to the latter, it expects dates in the | |
1460 | usual ranges used throughout this module: The year 2001 stays year 2001, | |
1461 | and months are numbered from 1 to 12. | |
1462 | .Sp | |
1463 | A fatal \*(L"date out of range\*(R" error will occur if the given date cannot | |
1464 | be expressed in terms of seconds since the epoch (this happens for | |
1465 | instance when the date lies before the epoch, or if it is later than | |
1466 | 19\-Jan\-2038\ 03:14:07\ \s-1GMT\s0 on 32\ bit Unix systems, or later than | |
1467 | 06\-Feb\-2040\ 06:28:15 (local time) on a Macintosh with MacOS Classic). | |
1468 | .Sp | |
1469 | Just like the \*(L"\fIPOSIX::mktime()\fR\*(R" function, this function uses the | |
1470 | \&\*(L"\fImktime()\fR\*(R" system call, internally. | |
1471 | .Sp | |
1472 | This means that the given date and time is considered to be in local time, | |
1473 | and that the value returned by this function will depend on your machine's | |
1474 | local settings such as the time zone, whether daylight savings time is | |
1475 | (or was, at the time) in effect, and the system clock itself. | |
1476 | .Sp | |
1477 | \&\fB\s-1BEWARE\s0\fR that \*(L"\fImktime()\fR\*(R" does not always return the same time value | |
1478 | as fed into \*(L"\fIlocaltime()\fR\*(R", when you feed the output of \*(L"\fIlocaltime()\fR\*(R" | |
1479 | back into \*(L"\fImktime()\fR\*(R", on some systems! | |
1480 | .Sp | |
1481 | I.e., "\f(CW\*(C`Mktime((Localtime($time))[0..5])\*(C'\fR\*(L" will not always return | |
1482 | the same value as given in \*(R"\f(CW$time\fR"! | |
1483 | .IP "\(bu" 2 | |
1484 | \&\f(CW\*(C`($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]);\*(C'\fR | |
1485 | .Sp | |
1486 | This function returns the difference between "\f(CW\*(C`localtime(time)\*(C'\fR\*(L" and | |
1487 | \&\*(R"\f(CW\*(C`gmtime(time)\*(C'\fR\*(L", which is the timezone offset in effect for the current | |
1488 | location and the given \*(R"\f(CW\*(C`time\*(C'\fR". | |
1489 | .Sp | |
1490 | This offset is positive if you are located to the east of Greenwich, | |
1491 | and is usually negative (except during daylight savings time, in some | |
1492 | locations) if you are located to the west of Greenwich. | |
1493 | .Sp | |
1494 | Note that this offset is influenced by all of the relevant system | |
1495 | settings and parameters on your machine; such as locales, environment | |
1496 | variables (e.g. "\f(CW\*(C`TZ\*(C'\fR") and the system clock itself. See the | |
1497 | relevant documentation on your system for more details. | |
1498 | .Sp | |
1499 | If the "\f(CW\*(C`time\*(C'\fR\*(L" is omitted, the \*(R"\f(CW\*(C`time()\*(C'\fR\*(L" function will | |
1500 | be called automatically, internally (similar to the built-in | |
1501 | functions \*(R"\f(CW\*(C`localtime()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`gmtime()\*(C'\fR" in Perl). | |
1502 | .Sp | |
1503 | A fatal \*(L"time out of range\*(R" error will occur if the given time value | |
1504 | is out of range \f(CW\*(C`[0..(~0>>1)]\*(C'\fR. | |
1505 | .Sp | |
1506 | The last item of the returned list is a flag which indicates whether | |
1507 | daylight savings time is currently in effect. This flag is negative | |
1508 | (\-1) if this information is not available on your system. It is zero | |
1509 | (0) when daylight savings time is off, and positive (+1) when daylight | |
1510 | savings time is on. | |
1511 | .Sp | |
1512 | Thus you can check very quickly whether daylight savings time is | |
1513 | currently in effect by evaluating this function in scalar context | |
1514 | (in scalar context, Perl returns the last item of a list): | |
1515 | .Sp | |
1516 | .Vb 1 | |
1517 | \& if (scalar Timezone > 0) { # yes, daylight savings time | |
1518 | .Ve | |
1519 | .Sp | |
1520 | However, a slightly more efficient way would be this: | |
1521 | .Sp | |
1522 | .Vb 1 | |
1523 | \& if (scalar System_Clock > 0) { # yes, daylight savings time | |
1524 | .Ve | |
1525 | .IP "\(bu" 2 | |
1526 | \&\f(CW\*(C`$time = Date_to_Time($year,$month,$day, $hour,$min,$sec);\*(C'\fR | |
1527 | .Sp | |
1528 | This function is a replacement for the \s-1BSD\s0 function \*(L"\fItimegm()\fR\*(R" | |
1529 | (which is not available on all Unix systems), which converts | |
1530 | a given date and time into a time value, i.e., into the number | |
1531 | of seconds since whatever moment in time your system considers to be | |
1532 | the \*(L"epoch\*(R". On Unix and most other systems this is the number of seconds | |
1533 | since January 1st 1970 at midnight (\s-1GMT\s0). On MacOS Classic this is the | |
1534 | number of seconds since January 1st 1904 at midnight (local time). | |
1535 | .Sp | |
1536 | Under Unix, the date and time are considered to be in \s-1UTC\s0 | |
1537 | (\*(L"Universal Time Coordinated\*(R", and so is the resulting time value. | |
1538 | .Sp | |
1539 | \&\s-1UTC\s0 is almost the same as \s-1GMT\s0 (or \*(L"Greenwich Mean Time\*(R"), except | |
1540 | that \s-1UTC\s0 has leap seconds (in order to account for small variations | |
1541 | in the rotation of the earth, for instance), whereas \s-1GMT\s0 does not. | |
1542 | .Sp | |
1543 | Under MacOS Classic, however, both input and output are | |
1544 | considered to be in local time. | |
1545 | .Sp | |
1546 | The ranges of year and month follow the same rules as throughout | |
1547 | the rest of this module (and not the contorted rules of its Unix | |
1548 | equivalent), i.e., the year \*(L"2001\*(R" stays \*(L"2001\*(R" and the month | |
1549 | ranges from 1 to 12. | |
1550 | .Sp | |
1551 | A fatal \*(L"date out of range\*(R" error will occur if the given date cannot | |
1552 | be expressed in terms of seconds since the epoch (this happens for | |
1553 | instance when the date lies before the epoch, or if it is later than | |
1554 | 19\-Jan\-2038\ 03:14:07\ \s-1GMT\s0 on 32\ bit Unix systems, or later than | |
1555 | 06\-Feb\-2040\ 06:28:15 (local time) on a Macintosh with MacOS Classic). | |
1556 | .Sp | |
1557 | This function should be very fast, because it is implemented in | |
1558 | a very straightforward manner and doesn't use any internal system | |
1559 | calls. | |
1560 | .Sp | |
1561 | Moreover, the functions \*(L"\fIDate_to_Time()\fR\*(R" and \*(L"\fITime_to_Date()\fR\*(R" | |
1562 | are guaranteed to be complementary, i.e., that | |
1563 | "\f(CW\*(C`Date_to_Time(Time_to_Date($time))\*(C'\fR\*(L" and | |
1564 | \&\*(R"\f(CW\*(C`Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))\*(C'\fR" | |
1565 | will always return the initial values. | |
1566 | .IP "\(bu" 2 | |
1567 | \&\f(CW\*(C`($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]);\*(C'\fR | |
1568 | .Sp | |
1569 | This function is an alternative to the \s-1POSIX\s0 \*(L"\fIgmtime()\fR\*(R" function | |
1570 | (and its built-in Perl equivalent), which converts a given time | |
1571 | value into the corresponding date and time. The given time value | |
1572 | must be the number of seconds since whatever moment in time your | |
1573 | system considers to be the \*(L"epoch\*(R". On Unix and most other systems | |
1574 | this is the number of seconds since January 1st 1970 at midnight | |
1575 | (\s-1GMT\s0). On MacOS Classic this is the number of seconds since | |
1576 | January 1st 1904 at midnight (local time). | |
1577 | .Sp | |
1578 | Under Unix, the given time value is considered to be in \s-1UTC\s0 | |
1579 | (\*(L"Universal Time Coordinated\*(R", and so is the resulting date | |
1580 | and time. | |
1581 | .Sp | |
1582 | \&\s-1UTC\s0 is almost the same as \s-1GMT\s0 (or \*(L"Greenwich Mean Time\*(R"), except | |
1583 | that \s-1UTC\s0 has leap seconds (in order to account for small variations | |
1584 | in the rotation of the earth, for instance), whereas \s-1GMT\s0 does not. | |
1585 | .Sp | |
1586 | Under MacOS Classic, however, both input and output | |
1587 | are considered to be in local time. | |
1588 | .Sp | |
1589 | If the input value "\f(CW\*(C`time\*(C'\fR\*(L" is omitted, the \*(R"\f(CW\*(C`time()\*(C'\fR\*(L" function | |
1590 | will be called automatically, internally (similar to the built-in | |
1591 | functions \*(R"\f(CW\*(C`localtime()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`gmtime()\*(C'\fR" in Perl). | |
1592 | .Sp | |
1593 | A fatal \*(L"time out of range\*(R" error will occur if the given time | |
1594 | value is negative. | |
1595 | .Sp | |
1596 | This function should be very fast, because it is implemented in | |
1597 | a very straightforward manner and doesn't use any internal system | |
1598 | calls (except for \*(L"\fItime()\fR\*(R", if the input value is omitted). | |
1599 | .Sp | |
1600 | Moreover, the functions \*(L"\fIDate_to_Time()\fR\*(R" and \*(L"\fITime_to_Date()\fR\*(R" | |
1601 | are guaranteed to be complementary, i.e., that | |
1602 | "\f(CW\*(C`Date_to_Time(Time_to_Date($time))\*(C'\fR\*(L" and | |
1603 | \&\*(R"\f(CW\*(C`Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))\*(C'\fR" | |
1604 | will always return the initial values. | |
1605 | .IP "\(bu" 2 | |
1606 | \&\f(CW\*(C`($year,$month,$day) = Easter_Sunday($year);\*(C'\fR | |
1607 | .Sp | |
1608 | This function calculates the date of Easter Sunday for all years in the | |
1609 | range from 1583 to 2299 (all other year numbers will result in a fatal | |
1610 | \&\*(L"year out of range\*(R" error message) using the method known as the \*(L"Gaussian | |
1611 | Rule\*(R". | |
1612 | .Sp | |
1613 | Some related christian feast days which depend on the date of Easter Sunday: | |
1614 | .Sp | |
1615 | .Vb 11 | |
1616 | \& Carnival Monday / Rosenmontag / Veille du Mardi Gras = -48 days | |
1617 | \& Mardi Gras / Karnevalsdienstag / Mardi Gras = -47 days | |
1618 | \& Ash Wednesday / Aschermittwoch / Mercredi des Cendres = -46 days | |
1619 | \& Palm Sunday / Palmsonntag / Dimanche des Rameaux = -7 days | |
1620 | \& Easter Friday / Karfreitag / Vendredi Saint = -2 days | |
1621 | \& Easter Saturday / Ostersamstag / Samedi de Paques = -1 day | |
1622 | \& Easter Monday / Ostermontag / Lundi de Paques = +1 day | |
1623 | \& Ascension of Christ / Christi Himmelfahrt / Ascension = +39 days | |
1624 | \& Whitsunday / Pfingstsonntag / Dimanche de Pentecote = +49 days | |
1625 | \& Whitmonday / Pfingstmontag / Lundi de Pentecote = +50 days | |
1626 | \& Feast of Corpus Christi / Fronleichnam / Fete-Dieu = +60 days | |
1627 | .Ve | |
1628 | .Sp | |
1629 | Use the offsets shown above to calculate the date of the corresponding | |
1630 | feast day as follows: | |
1631 | .Sp | |
1632 | .Vb 1 | |
1633 | \& ($year,$month,$day) = Add_Delta_Days(Easter_Sunday($year), $offset)); | |
1634 | .Ve | |
1635 | .IP "\(bu" 2 | |
1636 | \&\f(CW\*(C`if ($month = Decode_Month($string))\*(C'\fR | |
1637 | .Sp | |
1638 | This function takes a string as its argument, which should contain the | |
1639 | name of a month \fB\s-1IN\s0 \s-1THE\s0 \s-1CURRENTLY\s0 \s-1SELECTED\s0 \s-1LANGUAGE\s0\fR (see further below | |
1640 | for details about the multi-language support of this package), or any uniquely | |
1641 | identifying abbreviation of a month's name (i.e., the first few letters), | |
1642 | and returns the corresponding number (1..12) upon a successful match, or | |
1643 | "\f(CW0\fR\*(L" otherwise (therefore, the return value can also be used as the | |
1644 | conditional expression in an \*(R"if" statement). | |
1645 | .Sp | |
1646 | Note that the input string may not contain any other characters which do not | |
1647 | pertain to the month's name, especially no leading or trailing whitespace. | |
1648 | .Sp | |
1649 | Note also that matching is performed in a case-insensitive manner (this may | |
1650 | depend on the \*(L"locale\*(R" setting on your current system, though!) | |
1651 | .Sp | |
1652 | With \*(L"English\*(R" as the currently selected language (which is the default), | |
1653 | the following examples will all return the value "\f(CW9\fR": | |
1654 | .Sp | |
1655 | .Vb 4 | |
1656 | \& $month = Decode_Month("s"); | |
1657 | \& $month = Decode_Month("Sep"); | |
1658 | \& $month = Decode_Month("septemb"); | |
1659 | \& $month = Decode_Month("September"); | |
1660 | .Ve | |
1661 | .IP "\(bu" 2 | |
1662 | \&\f(CW\*(C`if ($dow = Decode_Day_of_Week($string))\*(C'\fR | |
1663 | .Sp | |
1664 | This function takes a string as its argument, which should contain the | |
1665 | name of a day of week \fB\s-1IN\s0 \s-1THE\s0 \s-1CURRENTLY\s0 \s-1SELECTED\s0 \s-1LANGUAGE\s0\fR (see further | |
1666 | below for details about the multi-language support of this package), or any | |
1667 | uniquely identifying abbreviation of the name of a day of week (i.e., the | |
1668 | first few letters), and returns the corresponding number (1..7) upon a | |
1669 | successful match, or "\f(CW0\fR\*(L" otherwise (therefore, the return value can | |
1670 | also be used as the conditional expression in an \*(R"if" statement). | |
1671 | .Sp | |
1672 | Note that the input string may not contain any other characters which | |
1673 | do not pertain to the name of the day of week, especially no leading | |
1674 | or trailing whitespace. | |
1675 | .Sp | |
1676 | Note also that matching is performed in a case-insensitive manner (this may | |
1677 | depend on the \*(L"locale\*(R" setting on your current system, though!) | |
1678 | .Sp | |
1679 | With \*(L"English\*(R" as the currently selected language (which is the default), | |
1680 | the following examples will all return the value "\f(CW3\fR": | |
1681 | .Sp | |
1682 | .Vb 4 | |
1683 | \& $dow = Decode_Day_of_Week("w"); | |
1684 | \& $dow = Decode_Day_of_Week("Wed"); | |
1685 | \& $dow = Decode_Day_of_Week("wednes"); | |
1686 | \& $dow = Decode_Day_of_Week("Wednesday"); | |
1687 | .Ve | |
1688 | .IP "\(bu" 2 | |
1689 | \&\f(CW\*(C`if ($lang = Decode_Language($string))\*(C'\fR | |
1690 | .Sp | |
1691 | This function takes a string as its argument, which should contain the | |
1692 | name of one of the languages supported by this package (\fB\s-1IN\s0 \s-1THIS\s0 \s-1VERY\s0 | |
1693 | \&\s-1LANGUAGE\s0 \s-1ITSELF\s0\fR), or any uniquely identifying abbreviation of the name | |
1694 | of a language (i.e., the first few letters), and returns its corresponding | |
1695 | internal number (1..13 in the original distribution) upon a successful match, | |
1696 | or "\f(CW0\fR\*(L" otherwise (therefore, the return value can also be used as the | |
1697 | conditional expression in an \*(R"if" statement). | |
1698 | .Sp | |
1699 | Note that the input string may not contain any other characters which do | |
1700 | not pertain to the name of a language, especially no leading or trailing | |
1701 | whitespace. | |
1702 | .Sp | |
1703 | Note also that matching is performed in a case-insensitive manner (this may | |
1704 | depend on the \*(L"locale\*(R" setting on your current system, though!) | |
1705 | .Sp | |
1706 | The original distribution supports the following thirteen languages: | |
1707 | .Sp | |
1708 | .Vb 13 | |
1709 | \& English ==> 1 (default) | |
1710 |