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