1Date::Manip::DM6(3) User Contributed Perl Documentation Date::Manip::DM6(3)
2
6 Date::Manip::DM6 - Date manipulation routines
7
9 use Date::Manip;
10 $version = DateManipVersion($flag);
12 Date_Init("VAR=VAL","VAR=VAL",...);
14 $date = ParseDate(\@args [,@opts]);
16 $date = ParseDate($string [,@opts]);
17 $date = ParseDate(\$string [,@opts]);
18 $date = ParseDateString($string [,@opts]);
20 $date = ParseDateFormat($format,$string);
22 @date = UnixDate($date,@format);
24 $date = UnixDate($date,@format);
25 $delta = ParseDateDelta(\@args [,$mode]);
27 $delta = ParseDateDelta($string [,$mode]);
28 $delta = ParseDateDelta(\$string [,$mode]);
29 @str = Delta_Format($delta, [$mode,] $dec,@format);
31 $str = Delta_Format($delta, [$mode,] $dec,@format);
32 $recur = ParseRecur($string,$base,$date0,$date1,$flags);
34 @dates = ParseRecur($string,$base,$date0,$date1,$flags);
35 $flag = Date_Cmp($date1,$date2);
37 $d = DateCalc($d1,$d2 [,$errref] [,$mode]);
39 $date = Date_SetTime($date,$hr,$min,$sec);
41 $date = Date_SetTime($date,$time);
42 $date = Date_SetDateField($date,$field,$val [,$nocheck]);
44 $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
46 $date = Date_GetPrev($date,$dow,$today,$time);
47 $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
49 $date = Date_GetNext($date,$dow,$today,$time);
50 $name = Date_IsHoliday($date);
52 @name = Date_IsHoliday($date);
53 $listref = Events_List($date);
55 $listref = Events_List($date0,$date1);
56 $date = Date_ConvTZ($date,$from,$to);
58 $flag = Date_IsWorkDay($date [,$flag]);
60 $date = Date_NextWorkDay($date,$off [,$time]);
62 $date = Date_PrevWorkDay($date,$off [,$time]);
64 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
66 In the following routines, $y may be entered as either a 2 or 4 digit
68 year (it will be converted to a 4 digit year based on the variable
69 YYtoYYYY described below). Month and day should be numeric in all
70 cases.
71 $day = Date_DayOfWeek($m,$d,$y);
73 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
74 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
75 $days = Date_DaysSince1BC($m,$d,$y);
76 $day = Date_DayOfYear($m,$d,$y);
77 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
78 $days = Date_DaysInYear($y);
79 $days = Date_DaysInMonth($m,$y);
80 $wkno = Date_WeekOfYear($m,$d,$y,$first);
81 $flag = Date_LeapYear($y);
82 $day = Date_DaySuffix($d);
83 $tz = Date_TimeZone();
84
86 DateManipVersion
87 $version = DateManipVersion($flag);
88 Returns the version of Date::Manip. If $flag is non-zero, timezone
90 information is also returned.
91 Date_Init
93 Date_Init("VAR=VAL","VAR=VAL",...);
94 The Date_Init function is used to set any of the Date::Manip
96 configuration variables described in the Date::Manip::Config
97 document.
98 The strings to pass in are of the form "VAR=VAL". Any number may
100 be included and they can come in any order. VAR may be any
101 configuration variable. VAL is any allowed value for that
102 variable. For example, to switch from English to French and use
103 non-US format (so that 12/10 is Oct 12), do the following:
104 Date_Init("Language=French","DateFormat=non-US");
106 Note that variables are parsed in the order they are given, so
108 "DateFormat=non-US", "ConfigFile=./manip.cnf" may not give the
109 expected result. To be safe, ConfigFile should always appear first
110 in the list.
111 ParseDate
113 $date = ParseDate(\@args [,@opts]);
114 $date = ParseDate($string [,@opts]);
115 $date = ParseDate(\$string [,@opts]);
116 This takes an array or a string containing a date and parses it.
118 When the date is included as an array (for example, the arguments
119 to a program) the array should contain a valid date in the first
120 one or more elements (elements after a valid date are ignored).
121 Elements containing a valid date are shifted from the array. The
122 largest possible number of elements which can be correctly
123 interpreted as a valid date are always used. If a string is
124 entered rather than an array, that string is tested for a valid
125 date. The string is unmodified, even if passed in by reference.
126 The ParseDate routine is primarily used to handle command line
128 arguments. If you have a command where you want to enter a date as
129 a command line argument, you can use Date::Manip to make something
130 like the following work:
131 mycommand -date Dec 10 1997 -arg -arg2
133 No more reading man pages to find out what date format is required
135 in a man page.
136 The @opts argument may contain values that can be passed to the
138 "Date::Manip::Date::parse" method.
139 Historical note: this is originally why the Date::Manip routines
141 were written (though long before they were released as the
142 Date::Manip module). I was using a bunch of programs (primarily
143 batch queue managers) where dates and times were entered as command
144 line options and I was getting highly annoyed at the many different
145 (but not compatible) ways that they had to be entered. Date::Manip
146 originally consisted of basically 1 routine which I could pass
147 "@ARGV" to and have it remove a date from the beginning.
148 ParseDateString
150 $date = ParseDateString($string [,@opts]);
151 This parses a string containing a date and returns it. Refer to the
153 Date::Manip::Date documentation for valid date formats. The date
154 returned is in the local time zone.
155 The @opts argument may contain values that can be passed to the
157 "Date::Manip::Date::parse" method.
158 ParseDateFormat
160 $date = ParseDateFormat($format,$string);
161 This parses a string containing a date based on a format string and
163 returns the date. Refer to the Date::Manip::Date documentation for
164 the parse_format method for more information. The date returned is
165 in the local time zone.
166 UnixDate
168 $out = UnixDate($date,$in);
169 @out = UnixDate($date,@in);
170 This takes a date and a list of strings containing formats roughly
172 identical to the format strings used by the UNIX date(1) command.
173 Each format is parsed and an array of strings corresponding to each
174 format is returned.
175 The formats are described in the Date::Manip::Date document.
177 ParseDateDelta
179 $delta = ParseDateDelta(\@args [,$mode]);
180 $delta = ParseDateDelta($string [,$mode]);
181 $delta = ParseDateDelta(\$string [,$mode]);
182 In the first form, it takes an array and shifts a valid delta from
184 it. In the other two forms, it parses a string to see if it
185 contains a valid delta.
186 A valid delta is returned if found. Otherwise, an empty string is
188 returned.
189 The delta can be converted to 'exact', 'semi', or 'approx' using
191 the Date::Manip::Delta::convert method if $mode is passed in.
192 Delta_Format
194 $out = Delta_Format($delta [,$mode], $dec,$in);
195 @out = Delta_Format($delta [,$mode], $dec,@in);
196 This is similar to the UnixDate routine except that it extracts
198 information from a delta.
199 When formatting fields in a delta, the Date::Manip 6.00 formats
201 have changed and are much more powerful. The old 5.xx formats are
202 still available for the Delta_Format command for backward
203 compatibility. These formats include:
204 %Xv : print the value of the field X
206 %Xd : print the value of the field X and all
208 smaller units in terms of X
209 %Xh : print the value of field X and all
211 larger units in terms of X
212 %Xt : print the value of all fields in
214 terms of X
215 These make use of the $mode and $dec arguments to determine how to
217 format the information.
218 $dec is an integer, and is required, It tells the number of decimal
220 places to use.
221 $mode is either "exact", "semi", or "approx" and defaults to
223 "exact" if it is not included.
224 In "exact" mode, only exact relationships are used. This means
226 that there can be no mixing of the Y/M, W/D, and H/MN/S segments
227 (for non-business deltas, or Y/M, W, and D/H/MN/S segments for
228 business deltas) because there is no exact relation between the
229 fields of each set.
230 In "semi" mode, the semi-approximate relationships are used so
232 there is no mixing between Y/M and W/D/H/MN/S.
233 In "approx" mode, approximate relationships are used so all fields
235 can mix.
236 The semi-approximate and approximate relationships are described in
238 the Date::Manip::Delta manual.
239 So, in "exact" mode, with a non-business delta, and $dec = 2, the
241 following are equivalent:
242 old style new style
244 --------- ---------
245 %Xv %Xv
246 %hd %.2hhs
247 %hh %.2hdh
248 %ht %.2hds
249 %yd %.2yyM
250 In "approximate" mode, the following are equivalent:
252 old style new style
254 --------- ---------
255 %Xv %Xv
256 %hd %.2hhs
257 %hh %.2hdh
258 %ht %.2hys
259 %yd %.2yys
260 If you want to use the new style formats in Delta_Format, use one
262 of the calls:
263 Delta_Format($delta, @in);
265 Delta_Format($delta, undef, @in);
266 If the first element of @in is an integer, you have to use the 2nd
268 form.
269 The old formats will remain available for the time being, though at
271 some point they may be deprecated.
272 DateCalc
274 $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
275 This takes two dates, deltas, or one of each and performs the
277 appropriate calculation with them. Dates must be a string that can
278 be parsed by ParseDateString. Deltas must be a string that can be
279 parsed by ParseDateDelta. Two deltas add together to form a third
280 delta. A date and a delta returns a 2nd date. Two dates return a
281 delta (the difference between the two dates).
282 Since the two items can be interpreted as either dates or deltas,
284 and since many strings can be interpreted as both a date or a
285 delta, it is a good idea to pass the input through ParseDateDelta,
286 if appropriate if there is any ambiguity. For example, the string
287 "09:00:00" can be interpreted either as a date (today at 9:00:00)
288 or a delta (9 hours). To avoid unexpected results, avoid calling
289 DateCalc as:
290 $d = DateCalc("09:00:00",$someothervalue);
292 Instead, call it as:
294 $d = DateCalc(ParseDate("09:00:00"),$someothervalue);
296 to force it to be a date, or:
298 $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
300 to force it to be a delta. This will avoid unexpected results.
302 Passing something through ParseDate is optional since they will be
303 treated as dates by default (and for performance reasons, you're
304 better off not calling ParseDate).
305 If there is no ambiguity, you are better off NOT doing this for
307 performance reasons. If the delta is a business delta, you
308 definitely should NOT do this.
309 One other thing to note is that when parsing dates, a delta can be
311 interpreted as a date relative to now. DateCalc will ALWAYS treat a
312 delta as a delta, NOT a date.
313 For details on how calculations are done, refer to the
315 Date::Manip::Calc documentation.
316 By default, math is done using an exact mode.
318 If two deltas, or a date and a delta are passed in, $mode may be
320 used to force the delta to be either business or non-business mode
321 deltas. If $mode is 0 or 1, the delta(s) will be non-business.
322 Otherwise, they will be business deltas. If $mode is passed in, it
323 will be used only if the business or non-business state was not
324 explicitly set in the delta. $mode can also be any of the modes
325 discussed in the Date::Manip::Calc documentation.
326 If two dates are passed in, $mode is used to determine the type of
328 calculation. By default, an exact delta is produced. If $mode is
329 1, an approximate delta is produced. If $mode is 2, a business
330 approximate (bapprox) mode calculation is done. If $mode is 3, a
331 exact business mode delta is produced.
332 If \$err is passed in, it is set to:
334 1 is returned if $d1 is not a delta or date
336 2 is returned if $d2 is not a delta or date
337 3 if any other error occurs.
338 This argument is optional, but if included, it must come before
340 $mode.
341 Nothing is returned if an error occurs.
343 ParseRecur
345 $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
346 @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
347 This parses a string containing a recurrence and returns a fully
349 specified recurrence, or a list of dates referred to.
350 $string can be any of the forms:
352 FREQ
354 FREQ*FLAGS
355 FREQ*FLAGS*BASE
356 FREQ*FLAGS*BASE*DATE0
357 FREQ*FLAGS*BASE*DATE0*DATE1
358 where FREQ is a frequence (see the Date::Manip::Delta
360 documentation), FLAGS is a comma separated list of flags, and BASE,
361 DATE0, and DATE1 are date strings. The dates and flags can also be
362 passed in as $base, $date0, $date1, and $flags, and these will
363 override any values in $string.
364 In scalar context, the fully specified recurrence (or as much
366 information as is available) will be returned. In list context, a
367 list of dates will be returned.
368 Date_Cmp
370 $flag = Date_Cmp($date1,$date2);
371 This takes two dates and compares them. Any dates that can be
373 parsed will be compared.
374 Date_GetPrev
376 $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
377 $date = Date_GetPrev($date,$dow, $curr [,$time]);
378 $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
379 $date = Date_GetPrev($date,undef,$curr,$time);
380 This takes a date (any string that may be parsed by
382 ParseDateString) and finds the previous occurrence of either a day
383 of the week, or a certain time of day.
384 This is documented in the "prev" method in Date::Manip::Date,
386 except that here, $time is a string (HH, HH:MN:, or HH:MN:SS), and
387 $dow may be a string of the form "Fri" or "Friday".
388 Date_GetNext
390 $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
391 $date = Date_GetNext($date,$dow, $curr [,$time]);
392 $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
393 $date = Date_GetNext($date,undef,$curr,$time);
394 Similar to Date_GetPrev.
396 Date_SetTime
398 $date = Date_SetTime($date,$hr,$min,$sec);
399 $date = Date_SetTime($date,$time);
400 This takes a date (any string that may be parsed by
402 ParseDateString) and sets the time in that date. For example, one
403 way to get the time for 7:30 tomorrow would be to use the lines:
404 $date = ParseDate("tomorrow");
406 $date = Date_SetTime($date,"7:30");
407 $time is a string (HH, HH:MN, or HH:MN:SS).
409 Date_SetDateField
411 $date = Date_SetDateField($date,$field,$val);
412 This takes a date and sets one of its fields to a new value.
414 $field is any of the strings "y", "m", "d", "h", "mn", "s" (case
415 insensitive) and $val is the new value.
416 Date_IsHoliday
418 $name = Date_IsHoliday($date);
419 @name = Date_IsHoliday($date);
420 This returns undef if $date is not a holiday, or a string
422 containing the name of the holiday otherwise (or a list of names in
423 list context). An empty string is returned for an unnamed holiday.
424 Date_IsWorkDay
426 $flag = Date_IsWorkDay($date [,$flag]);
427 This returns 1 if $date is a work day. If $flag is non-zero, the
429 time is checked to see if it falls within work hours. It returns
430 an empty string if $date is not valid.
431 Events_List
433 $ref = Events_List($date);
434 $ref = Events_List($date,0 [,$flag]);
435 $ref = Events_List($date,$date1 [,$flag]);
436 This returns a list of events. If $flag is not given, or is equal
438 to 0, the list (returned as a reference) is similar to the the list
439 returned by the Date::Manip::Date::list_events method with $format
440 = "dates". The only difference is that it is formatted slightly
441 different to be backward compatible with Date::Manip 5.xx.
442 The data from the list_events method is:
444 ( [DATE1, NAME1a, NAME1b, ...],
446 [DATE2, NAME2a, NAME2b, ...],
447 ...
448 )
449 The reference returned from Events_List (if $flag = 0) is:
451 [ DATE1, [NAME1a, NAME1b, ...],
453 DATE2, [DATE2a, DATE2b, ...],
454 ...
455 ]
456 For example, if the following events are defined:
458 2000-01-01 ; 2000-03-21 = Winter
460 2000-03-22 ; 2000-06-21 = Spring
461 2000-02-01 = Event1
462 2000-05-01 = Event2
463 2000-04-01-12:00:00 = Event3
464 the following examples illustrate the function:
466 Events_List("2000-04-01")
468 => [ 2000040100:00:00, [ Spring ] ]
469 Events_List("2000-04-01 12:30");
471 => [ 2000040112:30:00, [ Spring, Event3 ] ]
472 Events_List("2000-04-01",0);
474 => [ 2000040100:00:00, [ Spring ],
475 2000040112:00:00, [ Spring, Event3 ],
476 2000040113:00:00, [ Spring ] ]
477 Events_List("2000-03-15","2000-04-10");
479 => [ 2000031500:00:00, [ Winter ],
480 2000032200:00:00, [ Spring ]
481 2000040112:00:00, [ Spring, Event3 ]
482 2000040113:00:00, [ Spring ] ]
483 If $flag is 1, then a tally of the amount of time given to each
485 event is returned. Time for which two or more events apply is
486 counted for both.
487 Events_List("2000-03-15","2000-04-10",1);
489 => { Event3 => +0:0:+0:0:1:0:0,
490 Spring => +0:0:+2:4:23:0:0,
491 Winter => +0:0:+1:0:0:0:0
492 }
493 When $flag is 2, a more complex tally with no event counted twice
495 is returned.
496 Events_List("2000-03-15","2000-04-10",2);
498 => { Event3+Spring => +0:0:+0:0:1:0:0,
499 Spring => +0:0:+2:4:22:0:0,
500 Winter => +0:0:+1:0:0:0:0
501 }
502 The hash contains one element for each combination of events.
504 In both of these cases, there may be a hash element with an empty
506 string as the key which contains the amount of time with no events
507 active.
508 Date_DayOfWeek
510 $day = Date_DayOfWeek($m,$d,$y);
511 Returns the day of the week (1 for Monday, 7 for Sunday).
513 Date_SecsSince1970
515 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
516 Returns the number of seconds since Jan 1, 1970 00:00 (negative if
518 date is earlier) in the current timezone.
519 Date_SecsSince1970GMT
521 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
522 Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative
524 if date is earlier). Note that the date is still given in the
525 current timezone, NOT GMT.
526 Date_DaysSince1BC
528 $days = Date_DaysSince1BC($m,$d,$y);
529 Returns the number of days since Dec 31, 1BC. This includes the
531 year 0001.
532 Date_DayOfYear
534 $day = Date_DayOfYear($m,$d,$y);
535 Returns the day of the year (1 to 366)
537 Date_NthDayOfYear
539 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
540 Returns the year, month, day, hour, minutes, and decimal seconds
542 given a floating point day of the year.
543 All arguments must be numeric. $n must be greater than or equal to
545 1 and less than 366 on non-leap years and 367 on leap years.
546 NOTE: When $n is a decimal number, the results are non-intuitive
548 perhaps. Day 1 is Jan 01 00:00. Day 2 is Jan 02 00:00.
549 Intuitively, you might think of day 1.5 as being 1.5 days after Jan
550 01 00:00, but this would mean that Day 1.5 was Jan 02 12:00 (which
551 is later than Day 2). The best way to think of this function is a
552 time line starting at 1 and ending at 366 (in a non-leap year). In
553 terms of a delta, think of $n as the number of days after Dec 31
554 00:00 of the previous year.
555 Date_DaysInYear
557 $days = Date_DaysInYear($y);
558 Returns the number of days in the year (365 or 366)
560 Date_DaysInMonth
562 $days = Date_DaysInMonth($m,$y);
563 Returns the number of days in the month.
565 Date_WeekOfYear
567 $wkno = Date_WeekOfYear($m,$d,$y,$first);
568 Figure out week number. $first is the first day of the week which
570 is usually 1 (Monday) or 7 (Sunday), but could be any number
571 between 1 and 7 in practice.
572 NOTE: This routine should only be called in rare cases. Use
574 UnixDate with the %W, %U, %J, %L formats instead. This routine
575 returns a week between 0 and 53 which must then be "fixed" to get
576 into the ISO-8601 weeks from 1 to 53. A date which returns a week
577 of 0 actually belongs to the last week of the previous year. A
578 date which returns a week of 53 may belong to the first week of the
579 next year.
580 Date_LeapYear
582 $flag = Date_LeapYear($y);
583 Returns 1 if the argument is a leap year Written by David Muir
585 Sharnoff <muir@idiom.com>
586 Date_DaySuffix
588 $day = Date_DaySuffix($d);
589 Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th). Works
591 for international dates.
592 Date_TimeZone
594 $tz = Date_TimeZone;
595 This determines and returns the local time zone. If it is unable
597 to determine the local time zone, the following error occurs:
598 ERROR: Date::Manip unable to determine Time Zone.
600 See the Date::Manip::TZ documentation (DETERMINING THE LOCAL TIME
602 ZONE) for more information.
603 Date_ConvTZ
605 $date = Date_ConvTZ($date,$from,$to);
606 This converts a date (which MUST be in the format returned by
608 ParseDate) from one time zone to another.
609 $from and $to each default to the local time zone. If they are
611 given, they must be any time zone or alias understood by
612 Date::Manip.
613 If an error occurs, an empty string is returned.
615 Date_NextWorkDay
617 $date = Date_NextWorkDay($date,$off [,$time]);
618 Finds the day $off work days from now. If $time is passed in, we
620 must also take into account the time of day.
621 If $time is not passed in, day 0 is today (if today is a workday)
623 or the next work day if it isn't. In any case, the time of day is
624 unaffected.
625 If $time is passed in, day 0 is now (if now is part of a workday)
627 or the start of the very next work day.
628 Date_PrevWorkDay
630 $date = Date_PrevWorkDay($date,$off [,$time]);
631 Similar to Date_NextWorkDay.
633 Date_NearestWorkDay
635 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
636 This looks for the work day nearest to $date. If $date is a work
638 day, it is returned. Otherwise, it will look forward or backwards
639 in time 1 day at a time until a work day is found. If
640 $tomorrowfirst is non-zero (or if it is omitted and the config
641 variable TomorrowFirst is non-zero), we look to the future first.
642 Otherwise, we look in the past first. In other words, in a normal
643 week, if $date is Wednesday, $date is returned. If $date is
644 Saturday, Friday is returned. If $date is Sunday, Monday is
645 returned. If Wednesday is a holiday, Thursday is returned if
646 $tomorrowfirst is non-nil or Tuesday otherwise.
647 For all of the functions which return a date, the format of the
649 returned date is governed by the Printable config variable. If a date
650 is returned, it is in the local time zone, NOT the time zone the date
651 was parsed in.
652
654 Date::Manip - main module documentation
655
657 This script is free software; you can redistribute it and/or modify it
658 under the same terms as Perl itself.
659
661 Sullivan Beck (sbeck@cpan.org)
662perl v5.36.0 2023-03-08 Date::Manip::DM6(3)