1Date::Manip::DM6(3)   User Contributed Perl Documentation  Date::Manip::DM6(3)
2
3
4

NAME

6       Date::Manip::DM6 - Date manipulation routines
7

SYNOPSIS

9          use Date::Manip;
10
11          $version = DateManipVersion($flag);
12
13          Date_Init("VAR=VAL","VAR=VAL",...);
14
15          $date = ParseDate(\@args [,@opts]);
16          $date = ParseDate($string [,@opts]);
17          $date = ParseDate(\$string [,@opts]);
18
19          $date = ParseDateString($string [,@opts]);
20
21          $date = ParseDateFormat($format,$string);
22
23          @date = UnixDate($date,@format);
24          $date = UnixDate($date,@format);
25
26          $delta = ParseDateDelta(\@args   [,$mode]);
27          $delta = ParseDateDelta($string  [,$mode]);
28          $delta = ParseDateDelta(\$string [,$mode]);
29
30          @str = Delta_Format($delta, [$mode,] $dec,@format);
31          $str = Delta_Format($delta, [$mode,] $dec,@format);
32
33          $recur = ParseRecur($string,$base,$date0,$date1,$flags);
34          @dates = ParseRecur($string,$base,$date0,$date1,$flags);
35
36          $flag = Date_Cmp($date1,$date2);
37
38          $d = DateCalc($d1,$d2 [,$errref] [,$mode]);
39
40          $date = Date_SetTime($date,$hr,$min,$sec);
41          $date = Date_SetTime($date,$time);
42
43          $date = Date_SetDateField($date,$field,$val [,$nocheck]);
44
45          $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
46          $date = Date_GetPrev($date,$dow,$today,$time);
47
48          $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
49          $date = Date_GetNext($date,$dow,$today,$time);
50
51          $name = Date_IsHoliday($date);
52          @name = Date_IsHoliday($date);
53
54          $listref = Events_List($date);
55          $listref = Events_List($date0,$date1);
56
57          $date = Date_ConvTZ($date,$from,$to);
58
59          $flag = Date_IsWorkDay($date [,$flag]);
60
61          $date = Date_NextWorkDay($date,$off [,$time]);
62
63          $date = Date_PrevWorkDay($date,$off [,$time]);
64
65          $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
66
67       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
72          $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

ROUTINES

86       DateManipVersion
87              $version = DateManipVersion($flag);
88
89           Returns the version of Date::Manip.  If $flag is non-zero, timezone
90           information is also returned.
91
92       Date_Init
93              Date_Init("VAR=VAL","VAR=VAL",...);
94
95           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
99           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
105              Date_Init("Language=French","DateFormat=non-US");
106
107           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
112       ParseDate
113              $date = ParseDate(\@args [,@opts]);
114              $date = ParseDate($string [,@opts]);
115              $date = ParseDate(\$string [,@opts]);
116
117           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
127           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
132              mycommand -date Dec 10 1997 -arg -arg2
133
134           No more reading man pages to find out what date format is required
135           in a man page.
136
137           The @opts argument may contain values that can be passed to the
138           "Date::Manip::Date::parse" method.
139
140           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
149       ParseDateString
150              $date = ParseDateString($string [,@opts]);
151
152           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
156           The @opts argument may contain values that can be passed to the
157           "Date::Manip::Date::parse" method.
158
159       ParseDateFormat
160              $date = ParseDateFormat($format,$string);
161
162           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
167       UnixDate
168              $out = UnixDate($date,$in);
169              @out = UnixDate($date,@in);
170
171           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
176           The formats are described in the Date::Manip::Date document.
177
178       ParseDateDelta
179              $delta = ParseDateDelta(\@args   [,$mode]);
180              $delta = ParseDateDelta($string  [,$mode]);
181              $delta = ParseDateDelta(\$string [,$mode]);
182
183           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
187           A valid delta is returned if found. Otherwise, an empty string is
188           returned.
189
190           The delta can be converted to 'exact', 'semi', or 'approx' using
191           the Date::Manip::Delta::convert method if $mode is passed in.
192
193       Delta_Format
194              $out = Delta_Format($delta [,$mode], $dec,$in);
195              @out = Delta_Format($delta [,$mode], $dec,@in);
196
197           This is similar to the UnixDate routine except that it extracts
198           information from a delta.
199
200           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
205              %Xv  : print the value of the field X
206
207              %Xd  : print the value of the field X and all
208                     smaller units in terms of X
209
210              %Xh  : print the value of field X and all
211                     larger units in terms of X
212
213              %Xt  : print the value of all fields in
214                     terms of X
215
216           These make use of the $mode and $dec arguments to determine how to
217           format the information.
218
219           $dec is an integer, and is required, It tells the number of decimal
220           places to use.
221
222           $mode is either "exact", "semi", or "approx" and defaults to
223           "exact" if it is not included.
224
225           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
231           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
234           In "approx" mode, approximate relationships are used so all fields
235           can mix.
236
237           The semi-approximate and approximate relationships are described in
238           the Date::Manip::Delta manual.
239
240           So, in "exact" mode, with a non-business delta, and $dec = 2, the
241           following are equivalent:
242
243              old style    new style
244              ---------    ---------
245              %Xv          %Xv
246              %hd          %.2hhs
247              %hh          %.2hdh
248              %ht          %.2hds
249              %yd          %.2yyM
250
251           In "approximate" mode, the following are equivalent:
252
253              old style    new style
254              ---------    ---------
255              %Xv          %Xv
256              %hd          %.2hhs
257              %hh          %.2hdh
258              %ht          %.2hys
259              %yd          %.2yys
260
261           If you want to use the new style formats in Delta_Format, use one
262           of the calls:
263
264              Delta_Format($delta, @in);
265              Delta_Format($delta, undef, @in);
266
267           If the first element of @in is an integer, you have to use the 2nd
268           form.
269
270           The old formats will remain available for the time being, though at
271           some point they may be deprecated.
272
273       DateCalc
274            $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
275
276           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
283           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
291             $d = DateCalc("09:00:00",$someothervalue);
292
293           Instead, call it as:
294
295             $d = DateCalc(ParseDate("09:00:00"),$someothervalue);
296
297           to force it to be a date, or:
298
299             $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
300
301           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
306           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
310           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
314           For details on how calculations are done, refer to the
315           Date::Manip::Calc documentation.
316
317           By default, math is done using an exact mode.
318
319           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
327           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
333           If \$err is passed in, it is set to:
334
335              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
339           This argument is optional, but if included, it must come before
340           $mode.
341
342           Nothing is returned if an error occurs.
343
344       ParseRecur
345              $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
346              @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
347
348           This parses a string containing a recurrence and returns a fully
349           specified recurrence, or a list of dates referred to.
350
351           $string can be any of the forms:
352
353              FREQ
354              FREQ*FLAGS
355              FREQ*FLAGS*BASE
356              FREQ*FLAGS*BASE*DATE0
357              FREQ*FLAGS*BASE*DATE0*DATE1
358
359           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
365           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
369       Date_Cmp
370              $flag = Date_Cmp($date1,$date2);
371
372           This takes two dates and compares them. Any dates that can be
373           parsed will be compared.
374
375       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
381           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
385           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
389       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
395           Similar to Date_GetPrev.
396
397       Date_SetTime
398              $date = Date_SetTime($date,$hr,$min,$sec);
399              $date = Date_SetTime($date,$time);
400
401           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
405              $date = ParseDate("tomorrow");
406              $date = Date_SetTime($date,"7:30");
407
408           $time is a string (HH, HH:MN, or HH:MN:SS).
409
410       Date_SetDateField
411              $date = Date_SetDateField($date,$field,$val);
412
413           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
417       Date_IsHoliday
418              $name = Date_IsHoliday($date);
419              @name = Date_IsHoliday($date);
420
421           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
425       Date_IsWorkDay
426              $flag = Date_IsWorkDay($date [,$flag]);
427
428           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
432       Events_List
433              $ref = Events_List($date);
434              $ref = Events_List($date,0      [,$flag]);
435              $ref = Events_List($date,$date1 [,$flag]);
436
437           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
443           The data from the list_events method is:
444
445              ( [DATE1, NAME1a, NAME1b, ...],
446                [DATE2, NAME2a, NAME2b, ...],
447                ...
448              )
449
450           The reference returned from Events_List (if $flag = 0) is:
451
452              [ DATE1, [NAME1a, NAME1b, ...],
453                DATE2, [DATE2a, DATE2b, ...],
454                ...
455              ]
456
457           For example, if the following events are defined:
458
459             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
465           the following examples illustrate the function:
466
467             Events_List("2000-04-01")
468              => [ 2000040100:00:00, [ Spring ] ]
469
470             Events_List("2000-04-01 12:30");
471              => [ 2000040112:30:00, [ Spring, Event3 ] ]
472
473             Events_List("2000-04-01",0);
474              => [ 2000040100:00:00, [ Spring ],
475                   2000040112:00:00, [ Spring, Event3 ],
476                   2000040113:00:00, [ Spring ] ]
477
478             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
484           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
488             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
494           When $flag is 2, a more complex tally with no event counted twice
495           is returned.
496
497             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
503           The hash contains one element for each combination of events.
504
505           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
509       Date_DayOfWeek
510              $day = Date_DayOfWeek($m,$d,$y);
511
512           Returns the day of the week (1 for Monday, 7 for Sunday).
513
514       Date_SecsSince1970
515              $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
516
517           Returns the number of seconds since Jan 1, 1970 00:00 (negative if
518           date is earlier) in the current timezone.
519
520       Date_SecsSince1970GMT
521              $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
522
523           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
527       Date_DaysSince1BC
528              $days = Date_DaysSince1BC($m,$d,$y);
529
530           Returns the number of days since Dec 31, 1BC.  This includes the
531           year 0001.
532
533       Date_DayOfYear
534              $day = Date_DayOfYear($m,$d,$y);
535
536           Returns the day of the year (1 to 366)
537
538       Date_NthDayOfYear
539              ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
540
541           Returns the year, month, day, hour, minutes, and decimal seconds
542           given a floating point day of the year.
543
544           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
547           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
556       Date_DaysInYear
557              $days = Date_DaysInYear($y);
558
559           Returns the number of days in the year (365 or 366)
560
561       Date_DaysInMonth
562              $days = Date_DaysInMonth($m,$y);
563
564           Returns the number of days in the month.
565
566       Date_WeekOfYear
567              $wkno = Date_WeekOfYear($m,$d,$y,$first);
568
569           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
573           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
581       Date_LeapYear
582              $flag = Date_LeapYear($y);
583
584           Returns 1 if the argument is a leap year Written by David Muir
585           Sharnoff <muir@idiom.com>
586
587       Date_DaySuffix
588              $day = Date_DaySuffix($d);
589
590           Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th).  Works
591           for international dates.
592
593       Date_TimeZone
594              $tz = Date_TimeZone;
595
596           This determines and returns the local time zone.  If it is unable
597           to determine the local time zone, the following error occurs:
598
599              ERROR: Date::Manip unable to determine Time Zone.
600
601           See the Date::Manip::TZ documentation (DETERMINING THE LOCAL TIME
602           ZONE) for more information.
603
604       Date_ConvTZ
605              $date = Date_ConvTZ($date,$from,$to);
606
607           This converts a date (which MUST be in the format returned by
608           ParseDate) from one time zone to another.
609
610           $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
614           If an error occurs, an empty string is returned.
615
616       Date_NextWorkDay
617              $date = Date_NextWorkDay($date,$off [,$time]);
618
619           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
622           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
626           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
629       Date_PrevWorkDay
630              $date = Date_PrevWorkDay($date,$off [,$time]);
631
632           Similar to Date_NextWorkDay.
633
634       Date_NearestWorkDay
635              $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
636
637           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
648       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

SEE ALSO

654       Date::Manip        - main module documentation
655

LICENSE

657       This script is free software; you can redistribute it and/or modify it
658       under the same terms as Perl itself.
659

AUTHOR

661       Sullivan Beck (sbeck@cpan.org)
662
663
664
665perl v5.34.1                      2022-06-06               Date::Manip::DM6(3)
Impressum