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);
25 $delta = ParseDateDelta($string);
26 $delta = ParseDateDelta(\$string);
27 @str = Delta_Format($delta,$dec,@format);
29 $str = Delta_Format($delta,$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 $listref = Events_List($date);
52 $listref = Events_List($date0,$date1);
53 $date = Date_ConvTZ($date,$from,$to);
55 $flag = Date_IsWorkDay($date [,$flag]);
57 $date = Date_NextWorkDay($date,$off [,$time]);
59 $date = Date_PrevWorkDay($date,$off [,$time]);
61 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
63 In the following routines, $y may be entered as either a 2 or 4 digit
65 year (it will be converted to a 4 digit year based on the variable
66 YYtoYYYY described below). Month and day should be numeric in all
67 cases.
68 $day = Date_DayOfWeek($m,$d,$y);
70 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
71 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
72 $days = Date_DaysSince1BC($m,$d,$y);
73 $day = Date_DayOfYear($m,$d,$y);
74 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
75 $days = Date_DaysInYear($y);
76 $days = Date_DaysInMonth($m,$y);
77 $wkno = Date_WeekOfYear($m,$d,$y,$first);
78 $flag = Date_LeapYear($y);
79 $day = Date_DaySuffix($d);
80 $tz = Date_TimeZone();
81
83 DateManipVersion
84 $version = DateManipVersion($flag);
85 Returns the version of Date::Manip. If $flag is non-zero, timezone
87 information is also returned.
88 Date_Init
90 Date_Init("VAR=VAL","VAR=VAL",...);
91 The Date_Init function is used to set any of the Date::Manip
93 configuration variables described in the Date::Manip::Config
94 document.
95 The strings to pass in are of the form "VAR=VAL". Any number may
97 be included and they can come in any order. VAR may be any
98 configuration variable. VAL is any allowed value for that
99 variable. For example, to switch from English to French and use
100 non-US format (so that 12/10 is Oct 12), do the following:
101 Date_Init("Language=French","DateFormat=non-US");
103 Note that variables are parsed in the order they are given, so
105 "DateFormat=non-US", "ConfigFile=./manip.cnf" may not give the
106 expected result. To be safe, ConfigFile should always appear first
107 in the list.
108 ParseDate
110 $date = ParseDate(\@args);
111 $date = ParseDate($string);
112 $date = ParseDate(\$string);
113 This takes an array or a string containing a date and parses it.
115 When the date is included as an array (for example, the arguments
116 to a program) the array should contain a valid date in the first
117 one or more elements (elements after a valid date are ignored).
118 Elements containing a valid date are shifted from the array. The
119 largest possible number of elements which can be correctly
120 interpreted as a valid date are always used. If a string is
121 entered rather than an array, that string is tested for a valid
122 date. The string is unmodified, even if passed in by reference.
123 The ParseDate routine is primarily used to handle command line
125 arguments. If you have a command where you want to enter a date as
126 a command line argument, you can use Date::Manip to make something
127 like the following work:
128 mycommand -date Dec 10 1997 -arg -arg2
130 No more reading man pages to find out what date format is required
132 in a man page.
133 Historical note: this is originally why the Date::Manip routines
135 were written (though long before they were released as the
136 Date::Manip module). I was using a bunch of programs (primarily
137 batch queue managers) where dates and times were entered as command
138 line options and I was getting highly annoyed at the many different
139 (but not compatible) ways that they had to be entered. Date::Manip
140 originally consisted of basically 1 routine which I could pass
141 "@ARGV" to and have it remove a date from the beginning.
142 ParseDateString
144 $date = ParseDateString($string);
145 This parses a string containing a date and returns it. Refer to the
147 Date::Manip::Date documentation for valid date formats. The date
148 returned is in the local time zone.
149 UnixDate
151 $out = UnixDate($date,$in);
152 @out = UnixDate($date,@in);
153 This takes a date and a list of strings containing formats roughly
155 identical to the format strings used by the UNIX date(1) command.
156 Each format is parsed and an array of strings corresponding to each
157 format is returned.
158 The formats are described in the Date::Manip::Date document.
160 ParseDateDelta
162 $delta = ParseDateDelta(\@args);
163 $delta = ParseDateDelta($string);
164 $delta = ParseDateDelta(\$string);
165 In the first form, it takes an array and shifts a valid delta from
167 it. In the other two forms, it parses a string to see if it
168 contains a valid delta.
169 A valid delta is returned if found. Otherwise, an empty string is
171 returned.
172 Delta_Format
174 $out = Delta_Format($delta [,$mode], $dec,$in);
175 @out = Delta_Format($delta [,$mode], $dec,@in);
176 This is similar to the UnixDate routine except that it extracts
178 information from a delta.
179 When formatting fields in a delta, the Date::Manip 6.00 formats
181 have changed and are much more powerful. The old 5.xx formats are
182 still available for the Delta_Format command for backward
183 compatibility. These formats include:
184 %Xv : print the value of the field X
186 %Xd : print the value of the field X and all
188 smaller units in terms of X
189 %Xh : print the value of field X and all
191 larger units in terms of X
192 %Xt : print the value of all fields in
194 terms of X
195 These make use of the $mode and $dec arguments to determine how to
197 format the information.
198 $dec is an integer, and is required, It tells the number of decimal
200 places to use.
201 $mode is either "exact" or "approx" and defaults to "exact" if it
203 is not included.
204 In "exact" mode, only exact relationships are used. This means
206 that there can be no mixing of the Y/M and W/D/H/MN/S segments (for
207 non-business deltas, or Y/M, W, and D/H/MN/S segments for business
208 deltas) because there is no exact relation between the fields of
209 each set.
210 In "approx" mode, approximate relationships are used. These are
212 described in the Date::Manip::Delta manual.
213 So, in "exact" mode, with a non-business delta, and $dec = 2, the
215 following are equivalent:
216 old style new style
218 --------- ---------
219 %Xv %Xv
220 %hd %.2hhs
221 %hh %.2hdh
222 %ht %.2hds
223 %yd %.2yyM
224 In "approximate" mode, the following are equivalent:
226 old style new style
228 --------- ---------
229 %Xv %Xv
230 %hd %.2hhs
231 %hh %.2hdh
232 %ht %.2hys
233 %yd %.2yys
234 If you want to use the new style formats in Delta_Format, use one
236 of the calls:
237 Delta_Format($delta, @in);
239 Delta_Format($delta, undef, @in);
240 If the first element of @in is an integer, you have to use the 2nd
242 form.
243 The old formats will remain available for the time being, though at
245 some point they may be deprecated.
246 DateCalc
248 $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
249 This takes two dates, deltas, or one of each and performs the
251 appropriate calculation with them. Dates must be a string that can
252 be parsed by ParseDateString. Deltas must be a string that can be
253 parsed by ParseDateDelta. Two deltas add together to form a third
254 delta. A date and a delta returns a 2nd date. Two dates return a
255 delta (the difference between the two dates).
256 Since the two items can be interpreted as either dates or deltas,
258 and since many strings can be interpreted as both a date or a
259 delta, it is a good idea to pass the input through ParseDateDelta,
260 if appropriate if there is any ambiguity. For example, the string
261 "09:00:00" can be interpreted either as a date (today at 9:00:00)
262 or a delta (9 hours). To avoid unexpected results, avoid calling
263 DateCalc as:
264 $d = DateCalc("09:00:00",$someothervalue);
266 Instead, call it as:
268 $d = DateCalc(ParseDate("09:00:00"),$someothervalue);
270 to force it to be a date, or:
272 $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
274 to force it to be a delta. This will avoid unexpected results.
276 Passing something through ParseDate is optional since they will be
277 treated as dates by default (and for performance reasons, you're
278 better off not calling ParseDate).
279 If there is no ambiguity, you are better off NOT doing this for
281 performance reasons. If the delta is a business delta, you
282 definitely should NOT do this.
283 One other thing to note is that when parsing dates, a delta can be
285 interpreted as a date relative to now. DateCalc will ALWAYS treat a
286 delta as a delta, NOT a date.
287 For details on how calculations are done, refer to the
289 Date::Manip::Calc documentation.
290 By default, math is done using an exact mode.
292 If two deltas, or a date and a delta are passed in, $mode may be
294 used to force the delta to be either business or non-business mode
295 deltas. If $mode is 0 or 1, the delta(s) will be non-business.
296 Otherwise, they will be business deltas. If $mode is passed in, it
297 will be used only if the business or non-business state was not
298 explicitly set in the delta.
299 If two dates are passed in, $mode is used to determine the type of
301 calculation. By default, an exact delta is produced. If $mode is
302 1, an approximate delta is produced. If $mode is 2, a business
303 approximate (bapprox) mode calculation is done. If $mode is 3, a
304 exact business mode delta is produced.
305 If \$err is passed in, it is set to:
307 1 is returned if $d1 is not a delta or date
308 2 is returned if $d2 is not a delta or date
309 3 if any other error occurs. This argument is optional, but if
310 included, it must come before $mode.
311 Nothing is returned if an error occurs.
313 ParseRecur
315 $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
316 @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
317 This parses a string containing a recurrence and returns a fully
319 specified recurrence, or a list of dates referred to.
320 $string can be any of the forms:
322 FREQ
324 FREQ*FLAGS
325 FREQ*FLAGS*BASE
326 FREQ*FLAGS*BASE*DATE0
327 FREQ*FLAGS*BASE*DATE0*DATE1
328 where FREQ is a frequence (see the Date::Manip::Delta
330 documentation), FLAGS is a comma separated list of flags, and BASE,
331 DATE0, and DATE1 are date strings. The dates and flags can also be
332 passed in as $base, $date0, $date1, and $flags, and these will
333 override any values in $string.
334 In scalar context, the fully specified recurrence (or as much
336 information as is available) will be returned. In list context, a
337 list of dates will be returned.
338 Date_Cmp
340 $flag = Date_Cmp($date1,$date2);
341 This takes two dates and compares them. Any dates that can be
343 parsed will be compared.
344 Date_GetPrev
346 $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
347 $date = Date_GetPrev($date,$dow, $curr [,$time]);
348 $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
349 $date = Date_GetPrev($date,undef,$curr,$time);
350 This takes a date (any string that may be parsed by
352 ParseDateString) and finds the previous occurrence of either a day
353 of the week, or a certain time of day.
354 This is documented in the "prev" method in Date::Manip::Date,
356 except that here, $time is a string (HH, HH:MN:, or HH:MN:SS), and
357 $dow may be a string of the form "Fri" or "Friday".
358 Date_GetNext
360 $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
361 $date = Date_GetNext($date,$dow, $curr [,$time]);
362 $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
363 $date = Date_GetNext($date,undef,$curr,$time);
364 Similar to Date_GetPrev.
366 Date_SetTime
368 $date = Date_SetTime($date,$hr,$min,$sec);
369 $date = Date_SetTime($date,$time);
370 This takes a date (any string that may be parsed by
372 ParseDateString) and sets the time in that date. For example, one
373 way to get the time for 7:30 tomorrow would be to use the lines:
374 $date = ParseDate("tomorrow");
376 $date = Date_SetTime($date,"7:30");
377 $time is a string (HH, HH:MN, or HH:MN:SS).
379 Date_SetDateField
381 $date = Date_SetDateField($date,$field,$val);
382 This takes a date and sets one of its fields to a new value.
384 $field is any of the strings "y", "m", "d", "h", "mn", "s" (case
385 insensitive) and $val is the new value.
386 Date_IsHoliday
388 $name = Date_IsHoliday($date);
389 This returns undef if $date is not a holiday, or a string
391 containing the name of the holiday otherwise. An empty string is
392 returned for an unnamed holiday.
393 Date_IsWorkDay
395 $flag = Date_IsWorkDay($date [,$flag]);
396 This returns 1 if $date is a work day. If $flag is non-zero, the
398 time is checked to see if it falls within work hours. It returns
399 an empty string if $date is not valid.
400 Events_List
402 $ref = Events_List($date);
403 $ref = Events_List($date,0 [,$flag]);
404 $ref = Events_List($date,$date1 [,$flag]);
405 This returns a list of events. If $flag is not given, or is equal
407 to 0, the list (returned as a reference) is similar to the the list
408 returned by the Date::Manip::Date::list_events method with $format
409 = "dates". The only difference is that it is formatted slightly
410 different to be backward compatible with Date::Manip 5.xx.
411 The data from the list_events method is:
413 ( [DATE1, NAME1a, NAME1b, ...],
415 [DATE2, NAME2a, NAME2b, ...],
416 ...
417 )
418 The reference returned from Events_List (if $flag = 0) is:
420 [ DATE1, [NAME1a, NAME1b, ...],
422 DATE2, [DATE2a, DATE2b, ...],
423 ...
424 ]
425 For example, if the following events are defined:
427 2000-01-01 ; 2000-03-21 = Winter
429 2000-03-22 ; 2000-06-21 = Spring
430 2000-02-01 = Event1
431 2000-05-01 = Event2
432 2000-04-01-12:00:00 = Event3
433 the following examples illustrate the function:
435 Events_List("2000-04-01")
437 => [ 2000040100:00:00, [ Spring ] ]
438 Events_List("2000-04-01 12:30");
440 => [ 2000040112:30:00, [ Spring, Event3 ] ]
441 Events_List("2000-04-01",0);
443 => [ 2000040100:00:00, [ Spring ],
444 2000040112:00:00, [ Spring, Event3 ],
445 2000040113:00:00, [ Spring ] ]
446 Events_List("2000-03-15","2000-04-10");
448 => [ 2000031500:00:00, [ Winter ],
449 2000032200:00:00, [ Spring ]
450 2000040112:00:00, [ Spring, Event3 ]
451 2000040113:00:00, [ Spring ] ]
452 If $flag is 1, then a tally of the amount of time given to each
454 event is returned. Time for which two or more events apply is
455 counted for both.
456 Events_List("2000-03-15","2000-04-10",1);
458 => { Event3 => +0:0:+0:0:1:0:0,
459 Spring => +0:0:+2:4:23:0:0,
460 Winter => +0:0:+1:0:0:0:0
461 }
462 When $flag is 2, a more complex tally with no event counted twice
464 is returned.
465 Events_List("2000-03-15","2000-04-10",2);
467 => { Event3+Spring => +0:0:+0:0:1:0:0,
468 Spring => +0:0:+2:4:22:0:0,
469 Winter => +0:0:+1:0:0:0:0
470 }
471 The hash contains one element for each combination of events.
473 In both of these cases, there may be a hash element with an empty
475 string as the key which contains the amount of time with no events
476 active.
477 Date_DayOfWeek
479 $day = Date_DayOfWeek($m,$d,$y);
480 Returns the day of the week (1 for Monday, 7 for Sunday).
482 Date_SecsSince1970
484 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
485 Returns the number of seconds since Jan 1, 1970 00:00 (negative if
487 date is earlier).
488 Date_SecsSince1970GMT
490 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
491 Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative
493 if date is earlier).
494 Date_DaysSince1BC
496 $days = Date_DaysSince1BC($m,$d,$y);
497 Returns the number of days since Dec 31, 1BC. This includes the
499 year 0001.
500 Date_DayOfYear
502 $day = Date_DayOfYear($m,$d,$y);
503 Returns the day of the year (1 to 366)
505 Date_NthDayOfYear
507 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
508 Returns the year, month, day, hour, minutes, and decimal seconds
510 given a floating point day of the year.
511 All arguments must be numeric. $n must be greater than or equal to
513 1 and less than 366 on non-leap years and 367 on leap years.
514 NOTE: When $n is a decimal number, the results are non-intuitive
516 perhaps. Day 1 is Jan 01 00:00. Day 2 is Jan 02 00:00.
517 Intuitively, you might think of day 1.5 as being 1.5 days after Jan
518 01 00:00, but this would mean that Day 1.5 was Jan 02 12:00 (which
519 is later than Day 2). The best way to think of this function is a
520 time line starting at 1 and ending at 366 (in a non-leap year). In
521 terms of a delta, think of $n as the number of days after Dec 31
522 00:00 of the previous year.
523 Date_DaysInYear
525 $days = Date_DaysInYear($y);
526 Returns the number of days in the year (365 or 366)
528 Date_DaysInMonth
530 $days = Date_DaysInMonth($m,$y);
531 Returns the number of days in the month.
533 Date_WeekOfYear
535 $wkno = Date_WeekOfYear($m,$d,$y,$first);
536 Figure out week number. $first is the first day of the week which
538 is usually 1 (Monday) or 7 (Sunday), but could be any number
539 between 1 and 7 in practice.
540 NOTE: This routine should only be called in rare cases. Use
542 UnixDate with the %W, %U, %J, %L formats instead. This routine
543 returns a week between 0 and 53 which must then be "fixed" to get
544 into the ISO-8601 weeks from 1 to 53. A date which returns a week
545 of 0 actually belongs to the last week of the previous year. A
546 date which returns a week of 53 may belong to the first week of the
547 next year.
548 Date_LeapYear
550 $flag = Date_LeapYear($y);
551 Returns 1 if the argument is a leap year Written by David Muir
553 Sharnoff <muir@idiom.com>
554 Date_DaySuffix
556 $day = Date_DaySuffix($d);
557 Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th). Works
559 for international dates.
560 Date_TimeZone
562 $tz = Date_TimeZone;
563 This determines and returns the local time zone. If it is unable
565 to determine the local time zone, the following error occurs:
566 ERROR: Date::Manip unable to determine Time Zone.
568 See the Date::Manip::TZ documentation (DETERMINING THE LOCAL TIME
570 ZONE) for more information.
571 Date_ConvTZ
573 $date = Date_ConvTZ($date,$from,$to);
574 This converts a date (which MUST be in the format returned by
576 ParseDate) from one time zone to another.
577 $from and $to each default to the local time zone. If they are
579 given, they must be any time zone or alias understood by
580 Date::Manip.
581 If an error occurs, an empty string is returned.
583 Date_NextWorkDay
585 $date = Date_NextWorkDay($date,$off [,$time]);
586 Finds the day $off work days from now. If $time is passed in, we
588 must also take into account the time of day.
589 If $time is not passed in, day 0 is today (if today is a workday)
591 or the next work day if it isn't. In any case, the time of day is
592 unaffected.
593 If $time is passed in, day 0 is now (if now is part of a workday)
595 or the start of the very next work day.
596 Date_PrevWorkDay
598 $date = Date_PrevWorkDay($date,$off [,$time]);
599 Similar to Date_NextWorkDay.
601 Date_NearestWorkDay
603 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
604 This looks for the work day nearest to $date. If $date is a work
606 day, it is returned. Otherwise, it will look forward or backwards
607 in time 1 day at a time until a work day is found. If
608 $tomorrowfirst is non-zero (or if it is omitted and the config
609 variable TomorrowFirst is non-zero), we look to the future first.
610 Otherwise, we look in the past first. In other words, in a normal
611 week, if $date is Wednesday, $date is returned. If $date is
612 Saturday, Friday is returned. If $date is Sunday, Monday is
613 returned. If Wednesday is a holiday, Thursday is returned if
614 $tomorrowfirst is non-nil or Tuesday otherwise.
615 For all of the functions which return a date, the format of the
617 returned date is governed by the Printable config variable. If a date
618 is returned, it is in the local time zone, NOT the time zone the date
619 was parsed in.
620
622 Date::Manip - main module documentation
623
625 This script is free software; you can redistribute it and/or modify it
626 under the same terms as Perl itself.
627
629 Sullivan Beck (sbeck@cpan.org)
630perl v5.10.1 2011-12-07 Date::Manip::DM6(3)