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

NAME

6       Date::Manip::Date - Methods for working with dates
7

SYNOPSIS

9          use Date::Manip::Date;
10          $date = new Date::Manip::Date;
11

DESCRIPTION

13       This module works specifically with date objects.
14
15       Although the word date is used extensively here, it is actually
16       somewhat misleading.  Date::Manip works with the full calendar date
17       (year, month, day, and week when appropriate), time of day (hour,
18       minute, second), and time zone.  It doesn't work with fractional
19       seconds.
20

METHODS

22       base
23       config
24       err
25       is_date
26       is_delta
27       is_recur
28       new
29       new_config
30       new_date
31       new_delta
32       new_recur
33       tz  Please refer to the Date::Manip::Obj documentation for these
34           methods.
35
36       calc
37              $date2 = $date->calc($delta [,$subtract]);
38              $delta = $date->calc($date2 [,$subtract] [,$mode]);
39
40           Please refer to the Date::Manip::Calc documentation for details.
41
42       cmp
43              $val = $date1->cmp($date2);
44
45           This compares two different dates (both of which must be valid date
46           objects). It returns -1, 0, or 1 similar to the cmp or <=>
47           operators in perl. The comparison will automatically handle time
48           zone differences between the two dates (i.e. they will be sorted in
49           order as they appear in the GMT zone).
50
51           A warning is printed if either of the date objects does not include
52           a valid date.
53
54       complete
55              $flag = $date->complete([$field]);
56
57           This tests the date stored in the object to see if it is complete
58           or truncated (see below for a discussion of this).
59
60           If no $field is passed in, it returns 1 if the date is complete, or
61           0 if it was truncated and default values have been supplied.
62
63           If $field is passed in, it may be one of: m, d, h, mn, s . It will
64           return 1 if the value for that field was specified, or 0 if a
65           default was used.
66
67       convert
68              $err = $date->convert([$zone]);
69
70           This converts the date stored in the object to a different time
71           zone.  $zone can be the name of a time zone. If it is not passed
72           in, the date is converted to the local time zone.
73
74       holiday
75              $name = $date->holiday();
76              @name = $date->holiday();
77              $name = $date->event();
78
79           This returns the name of the holiday if $date is a holiday. If
80           $date is not a holiday, undef is returned. If $date is an unnamed
81           holiday, an empty string is returned.
82
83           In scalar context, holiday returns the name of one holiday that
84           occurs on that date (the one first defined in the config file).  In
85           list context, it returns all holidays on that date.
86
87       input
88              $str = $date->input();
89
90           This returns the string that was parsed to form the date.
91
92       is_business_day
93              $flag = $date->is_business_day($checktime);
94
95           This returns 1 if $date is a business day.
96
97           $checktime may be passed in. If it is non-zero, the time is checked
98           to see if the date is a business day and falls within work hours.
99
100       list_holidays
101             @date = $date->list_holidays([$y]);
102
103           This returns a list of Date::Manip::Date objects containing all
104           dates during a year which are holidays. The times will all be
105           00:00:00.
106
107           If $y is not passed in, it will list the holidays in the same year
108           as the date stored in $date (if any) or in the current year
109           otherwise.
110
111       list_events
112              @list = $date->list_events(       [$format] );
113              @list = $date->list_events(0      [,$format]);
114              @list = $date->list_events($date1 [,$format]);
115
116           This returns a list of events.  Events are defined in the Events
117           section of the config file (discussed in the Date::Manip::Holidays
118           manual).
119
120           In the first form, a list of all events active at the precise time
121           stored in $date will be returned.
122
123           If the first argument evaluates to 0, a list of all events active
124           at any time during that day (Y,M,D) are returned.
125
126           If the first argument is another date object, all events that are
127           active at any time between the two dates (inclusive) are returned.
128
129           By default, the list returned is of the form:
130
131              ( [START, END, NAME],
132                [START, END, NAME],
133                ...
134              )
135
136           where START is a date object when an event starts, END is a date
137           object when it ends, and NAME is the name of the event. Note that
138           START and END are the actual start and end date of the event and
139           may be outside the range of dates being examined (though the event
140           will obviously overlap the range or it wouldn't be included in the
141           list).
142
143           If $format is included, it can specify an alternate format for the
144           output. Currently, the only supported format is named "dates" and
145           it returns a list in the form:
146
147              ( [DATE1, NAME1a, NAME1b, ...],
148                [DATE2, NAME2a, NAME2b, ...],
149                ...
150              )
151
152           This includes a list of all dates during the range when there is a
153           change in what events are active. DATE1 will always be the start of
154           the range being considered, and (NAME1a, NAME1b, ...) are the list
155           of all events that will be active at that time. At DATE2, the list
156           of active events changes with (NAME2a, NAME2b, ...) being active.
157
158           It is quite possible that a date be included which has no active
159           events, and in that case, the list of names will be empty.
160
161       nearest_business_day
162              $date->nearest_business_day([$tomorrowfirst]);
163
164           This looks for the work day nearest to $date.  If $date is a work
165           day, it is left unmodified.  Otherwise, it will look forward or
166           backwards in time 1 day at a time until a work day is found.  If
167           $tomorrowfirst is non-zero (or if it is omitted and the config
168           variable TomorrowFirst is non-zero), we look to the future first.
169           Otherwise, we look in the past first.  In other words, in a normal
170           week, if $date is Wednesday, $date is returned.  If $date is
171           Saturday, Friday is returned.  If $date is Sunday, Monday is
172           returned.  If Wednesday is a holiday, Thursday is returned if
173           $tomorrowfirst is non-nil or Tuesday otherwise.
174
175       next_business_day
176       prev_business_day
177              $date->next_business_day($off [,$checktime]);
178              $date->prev_business_day($off [,$checktime]);
179
180           The next_business_day method sets the given date to $off (which can
181           be a positive integer or zero) business days in the future. The
182           prev_business_day method sets the date to $off business days in the
183           past.
184
185           First, $date is tested. If $checktime is nonzero, the date must
186           fall on a business date, and during business hours. If $checktime
187           is zero, the time check is not done, and the date must simply fall
188           on a business date.
189
190           If the check fails, the date is moved to the start of the next
191           business day (if $checktime is nonzero) or the next business day at
192           the current time (if $checktime is zero). Otherwise, it is left
193           unmodified.
194
195           Next, if $off is greater than 0, the day $off work days from now is
196           determined.
197
198           One thing to note for the prev_business_day method is that if $date
199           check fails, the date is set to the next business date, exactly
200           like next_business_day. In other words, if $date is not a business
201           day, the call:
202
203              $date->prev_business_day(0 [,$checktime]);
204
205           moves $date forward in time instead of backward which is
206           nonintuitive, but you just have to think of day 0 as being the next
207           business day if $date is not a business day.
208
209           As a result, the following two calls ALWAYS give the same result:
210
211              $date->next_business_day(0 [,$checktime]);
212              $date->prev_business_day(0 [,$checktime]);
213
214           no matter what date is stored in $date.
215
216       parse
217              $err = $date->parse($string [,@opts]);
218
219           This parses a string which should include a valid date and stores
220           it in the object. If the string does not include a valid date, an
221           error is returned. Use the err method to see the full error
222           message.
223
224           A full date may include a calendar date (year, month, day), a time
225           of day (hour, minute, second), and time zone information. All of
226           this can be entered in many different formats.
227
228           For information on valid date formats, refer to the section VALID
229           DATE FORMATS. For information on valid time zone information, refer
230           to the section VALID TIME ZONE FORMATS.
231
232           If no time zone information is included in the date, it is treated
233           as being in the local time zone.
234
235           If time zone information is included, the date will be kept in that
236           time zone, and all operations will be done in that time zone.  The
237           convert method can be used to change the time zone to the local
238           time zone, or to another time zone.
239
240           Some things to note:
241
242           All strings are case insensitive.  "December" and "DEceMBer" are
243           equivalent.
244
245           When a part of the date is not given, defaults are used. This is
246           described below in the section "Complete vs. truncated dates and
247           times".
248
249           The year may be entered as 2 or 4 digits.  If entered as 2 digits,
250           it will be converted to a 4 digit year.  There are several ways to
251           do this based on the value of the YYtoYYYY config variable.  Refer
252           to the Date::Manip::Config documentation for more details.
253
254           Dates are always checked to make sure they are valid.
255
256           If any other arguments are passed in, they act as options which may
257           improve the speed of parsing. These include:
258
259              noiso8601  Do not try to parse the
260                         date as an ISO 8601 date
261                         or time.
262              nodow      Do not try to parse a
263                         day-of-week (Monday) in
264                         the string.
265              nocommon   Do not try to parse the
266                         date using the formats
267                         in the "Common date
268                         formats" section.
269              noother    Do not try to parse the
270                         date using the "Less common
271                         date formats" or a time
272                         using the "Other time
273                         formats".
274              nospecial  Do not try to parse the
275                         date using the "Special
276                         date strings" formats
277                         or a time using the
278                         "Special time strings"
279                         formats, or as a
280                         combined date/time using
281                         the "Additional combined
282                         date and time" formats.
283              nodelta    Do not treat deltas as
284                         a date relative to now.
285              noholidays Do not parse holiday
286                         names as dates.
287
288       parse_date
289              $err = $date->parse_date($string [,@opts]);
290
291           This parses a string which contains a valid date and sets the date
292           part of the object.
293
294           If the object contained a valid date, the time is kept unchanged.
295           If the object did NOT contain a valid date, a time of 00:00:00 is
296           used.
297
298           @opts can be any of the strings described in the parse method
299           above.
300
301       parse_time
302              $err = $date->parse_time($string [,@opts]);
303
304           This parses a string and sets the time portion of $date to contain
305           it.
306
307           If the object contained a valid date, the Y/M/D portion is left
308           unchanged.  Otherwise, the current date is used.
309
310           @opts can be 'noiso8601' or 'noother'.
311
312       parse_format
313              $err          = $date->parse_format($format,$string);
314              ($err,%match) = $date->parse_format($format,$string);
315
316           This will parse a date contained in $string based on explicit
317           format information contained in $format.
318
319           If the format is invalid, $err will contain an error message.  If
320           the format is valid, but string doesn't match, an error code of 1
321           is returned.
322
323           If called in array context, a hash will be returned containing %+.
324           This is primarily useful if the $format string contains some named
325           capture groups that you define.  This is discussed below.
326
327           $format is a string containing a regular expression with some
328           special directives (based on the printf directives). These
329           directives are turned into regular expression components, and then
330           the entire string is turned into a regular expression which, if
331           $string matches it, will return the date.
332
333           The directives available are identical to the printf directives.
334           So, if your $format string contains the directive '%Y', it will
335           match a 4-digit year.
336
337           All of the printf directives are available here with a few caveats:
338
339              %l        This directive is NOT available.
340
341              %b,%h,%B  These will all match a month name or abbreviation.
342
343              %v,%a,%A  These will all match a day name or abbreviation.
344
345              %z,%Z,%N  These will match any time zone string.
346
347              %n        Multi-line matching is not currently supported,
348                        so this directive is not allowed.
349
350              %x        All format directives are converted to a regular
351                        expression and then cached (so that a format
352                        can be reused without the penalty of doing the
353                        conversion to a regular expression with each use).
354                        As a result, if you need to set the DateFormat config
355                        variable (which determines the meaning of the %x
356                        directive), it must be done before a format string
357                        containing %x is used. If the DateFormat config variable
358                        is set afterwards, the format string will reflect the
359                        old, NOT THE NEW, value of DateFormat.
360
361           The format string may not over-specify the date. In other words,
362           you may not include both a %y and %Y directive or both a %j and %m
363           directive.
364
365           A valid format string will specify any of the following sets of
366           data:
367
368              Required          Optional
369
370              M D H Mn S        Y Zone Day-of-week
371              M D H Mn          Y Zone Day-of-week
372              M D               Y Zone Day-of-week
373              H Mn S            Zone
374              H Mn              Zone
375
376           For example, if you had a date stored as:
377
378              YYYY.MM-DD
379
380           you could match it using the following:
381
382              $date->parse_format('%Y\\.%m\\-%d',$string);
383
384           If you wanted to extract the date from an apache log line:
385
386              10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] "GET /favicon.ico ...
387
388           you could use:
389
390              $date->parse_format('.*?\\[%d/%b/%Y:%T %z\\].*',$line);
391
392           When matching months, days, and hours, there are two directives
393           that could be used (for numerical versions).  For the month, you
394           may use %m or %f.  If your date is known to have a two-digit month,
395           you should use %m.  If it contains a one- or two-digit month, you
396           must use %f (and it is safe to use %f for two-digit months).
397           Similarly, for days, you can use %d or %e and for hours you can use
398           %H or %k.  In both cases, the first can only be used if you are
399           guaranteed a 2-digit value.
400
401           In your format string, you may use capture groups (or back
402           references to them) in the regular expression using all of the
403           rules of normal regular expressions. Since Date::Manip uses named
404           capture groups internally, it is suggested that you also use named
405           groups.  Mixing numbered and named groups will work... but it'll be
406           entirely up to you to keep track of what numbers refer to which
407           capture groups.
408
409           Every printf directive adds one or more named capture groups to the
410           regular expression.  If you use named groups in the format string,
411           they must not conflict with the ones used internally, or else the
412           date will probably not be parsed correctly.
413
414           The following named capture groups are used internally:
415
416              y
417              m
418              d
419              h
420              mn
421              s
422              mon_name
423              mon_abb
424              dow_name
425              dow_abb
426              dow_char
427              dow_num
428              doy
429              nth
430              ampm
431              epochs
432              epocho
433              tzstring
434              off
435              abb
436              zone
437              g
438              w
439              l
440              u
441
442           To be safe, it is suggested that any additional named capture
443           groups introduced by the programmer start with a capital letter.
444           This is guaranteed to never conflict with any existing, or future
445           named capture groups.
446
447           In order to get access to the values stored in the additional named
448           capture groups, the parse_format function must be called in list
449           context, and the %+ array will be returned as the second value.
450
451           As an example:
452
453              $string = "before 2014-01-25 after";
454              ($err,%m) = $date->parse_format('(?<PRE>.*?)%Y-%m-%d(?<POST>.*)',$string);
455
456           would return a hash (%m) with the following key/value pairs:
457
458              'PRE'  => 'before '
459              'POST' => ' after'
460
461       prev
462       next
463           The prev method changes the date to the previous (or current)
464           occurrence of either a day of the week, a certain time of day, or
465           both. The next method changes the date to the next (or current)
466           occurrence. The examples below illustrate the prev method, but the
467           next one is identical in operation.
468
469           There are two different ways to use this method. The first is to
470           pass in a day of week and possibly a time:
471
472              $err = $date->prev($dow, $curr [,$time]);
473
474           If $curr = 0, this means to look for the previous occurrence of the
475           day of week, and set the time to the value passed in (or current
476           time if no time was passed in). The day is ALWAYS less than the
477           current day. If the current day is the same day of week as $dow,
478           then the date returned will be one week earlier.
479
480           If $curr = 1, it means to look for the current or previous
481           occurrence of the day of week, and set the time to the value passed
482           in (or 00:00:00 if none was passed in). If the current day of week
483           is the same as $dow, the date will remain unchanged. Since the time
484           is then set, the new date may actually occur after the original
485           date depending on the value of $time.
486
487           If $curr = 2, it means to look for the last time (not counting now)
488           that the day of week at the given time occurred. The date may be
489           the same as the original date.
490
491           $time may be a list reference of [H,MN,S], [H,MN], or [H].
492
493           The following examples should illustrate the use of this function.
494
495               Original Date = Fri Nov 22 18:15:00
496
497               dow      curr   time       new date
498
499               4 (Thu)  0/1/2  undef      Thu Nov 21 00:00:00
500               4        0/1/2  [12,30,0]  Thu Nov 21 12:30:00
501
502               5 (Fri)  0/2    undef      Fri Nov 15 18:15:00
503               5        1      undef      Fri Nov 22 18:15:00
504
505               5        0      [12,30,0]  Fri Nov 15 12:30:00
506               5        1/2    [12,30,0]  Fri Nov 22 12:30:00
507
508               5        0/2    [19,30,0]  Fri Nov 15 19:30:00
509               5        1      [19,30,0]  Fri Nov 22 19:30:00
510
511           The second way to use this method is by passing in undef for the
512           day of week.
513
514              $err = $date->prev(undef,$curr,$time);
515
516           In this case, a time is required and it must be a list reference of
517           3 elements: [H, MN, S]. Any or all of the elements may be undef.
518
519           The new date is the previous occurrence of the time.
520
521           If you define hours, then minutes and seconds may be defined, or
522           default to 0 and you are looking for a previous time that the
523           specified time (HH:00:00) occurred (which might be as much as 24
524           hours in the past).
525
526           If hours are undefined and minutes are defined, then seconds may be
527           defined, or default to 0, and you are looking for the last time the
528           minutes/seconds (MN:SS) appeared on the digital clock, which will
529           be sometime in the past hour.
530
531           Finally, if hours and minutes are undefined, seconds must be
532           defined (or default to zero) and the last time that that second
533           occurred will be returned (which will be sometime in the past
534           minute).
535
536           If $curr is non-zero, the current time is returned if it matches
537           the criteria passed in, so the returned value will be now or in the
538           past.  If $curr is zero, the time returned will definitely be in
539           the past.
540
541               DATE = Fri Nov 22 18:15:00
542
543               curr  hr     min    sec      returns
544               0/1   18     undef  undef    Nov 22 18:00:00
545               0/1   18     30     0        Nov 21 18:30:00
546               0     18     15     undef    Nov 21 18:15:00
547               1     18     15     undef    Nov 22 18:15:00
548               0     undef  15     undef    Nov 22 17:15:00
549               1     undef  15     undef    Nov 22 18:15:00
550
551       printf
552              $out = $date->printf($in);
553              @out = $date->printf(@in);
554
555           This takes a string or list of strings which may contain any number
556           of special formatting directives. These directives are replaced
557           with information contained in the date. Everything else in the
558           string is returned unmodified.
559
560           A directive always begins with '%'. They are described in the
561           section below in the section PRINTF DIRECTIVES.
562
563       secs_since_1970_GMT
564              $secs = $date->secs_since_1970_GMT();
565
566           This returns the number of seconds that have elapsed since Jan 1,
567           1970 00:00:00 GMT (negative if the date is earlier).
568
569           The reverse is also allowed:
570
571              $err = $date->secs_since_1970_GMT($secs);
572
573           which sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT
574           in the local time zone.
575
576       set
577              $err = $date->set($field,@vals [,$isdst]);
578
579           This explicitly sets one or more fields in a date.
580
581           $field can be any of the following:
582
583              $field   @vals
584
585              zone     [ZONE]         ZONE can be any zone or alias
586
587              zdate    [ZONE,]DATE    sets the zone and entire date
588
589              date     DATE           sets the entire date
590
591              time     TIME           sets the entire time
592
593              y        YEAR           sets one field
594              m        MONTH
595              d        DAY
596              h        HOUR
597              mn       MINUTE
598              s        SECOND
599
600           Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME
601           is a list reference containing [H,MN,S].
602
603           ZONE is optional (it defaults to the local zone as defined either
604           by the system clock, or the SetDate or ForceDate config variables).
605           If it is passed in, it can be any zone name, abbreviation, or
606           offset. An offset can be expressed either as a valid offset string,
607           or as a list reference.  Refer to the join/split functions of
608           Date::Manip::Base for information on valid offset strings.
609
610           An optional last argument is $isdst (which must be 0 or 1) is
611           included when setting a date which could be in either standard time
612           or daylight saving time. It is ignored in all other situations. If
613           it is not included, and the resulting date could be in either, it
614           will default to standard time.
615
616           The $date object must contain a valid date (unless the entire date
617           is being set with $field set to either "zdate" or "date").
618
619           If $field is "zone", the time zone of the date will be set. If ZONE
620           is not passed in, it will be set to the local time zone.  When
621           setting the time zone, no conversion is done! Whatever date and
622           time is stored in the $date object prior to this remains
623           unchanged... except it will be that date and time in the new time
624           zone.
625
626           If $field is "zdate", the entire date and time zone is set. If ZONE
627           is not passed in, it is set to the local time zone.
628
629           If $field is "date", the entire date will be set, but the time zone
630           of the date will not be changed.
631
632           If $field is "time", or one of the individual fields, only those
633           fields will be modified.
634
635           An error is returned if an invalid argument list is passed in, or
636           if the resulting date is checked and found to be invalid.
637
638       value
639              $val = $date->value([$type]);
640              @val = $date->value([$type]);
641
642           These return the value of the date stored in the object.
643
644           In scalar context, a printable string in the form YYYYMMDDHH:MN:SS
645           is returned. In list context, a list is returned of (Y,M,D,H,MN,S).
646
647           If $type is omitted, the date is returned in the time zone it was
648           parsed in.
649
650           If $type is "local", it is returned in the local time zone (which
651           is either the system time zone, or the zone specified with the
652           SetDate or ForceDate config variables).
653
654           If $type is "gmt", the date is returned in the GMT time zone.
655
656           An empty string or list is returned in the case of an error (and an
657           error code is set).
658
659       week_of_year
660              $wkno = $date->week_of_year([$first]);
661
662           This figures out the week number. If $first is passed in, it must
663           be between 1 and 7 and refers to the first day of the week. If
664           $first is not passed in, the FirstDay config variable is used.
665
666           NOTE: This routine should only be called in rare cases.  Use printf
667           with the %W, %U, %J, %L formats instead.  This routine returns a
668           week between 0 and 53 which must then be "fixed" to get into the
669           ISO 8601 weeks from 1 to 53.  A date which returns a week of 0
670           actually belongs to the last week of the previous year.  A date
671           which returns a week of 53 may belong to the first week of the next
672           year.
673

ISSUES WITH PARSING DATES

675       The following issues may occur when parsing dates that should be
676       understood to make full use of this module.
677
678       Complete vs. truncated dates and times
679           Date formats are either complete or truncated. A complete date
680           fully specifies the year, month, and day and a complete time fully
681           specifies the hour, minute, and second.
682
683           It should be understood that in many instances, the information may
684           be implied rather than explicitly stated, but it is still treated
685           as complete.
686
687           For example, the date "January 3" is complete because it implies
688           the current year.
689
690           A truncated calendar date or time does not include information
691           about some of the fields. Date::Manip will never work with a
692           partial date or time, so defaults will be supplied.
693
694           For example, the date "2009-01" is missing a day field, so a
695           default will be used. In this case, the day will be the 1st, so
696           this is equivalent to "Jan 1st 2009". If only the year is given, it
697           will default to Jan 1.
698
699           If the time, or any of it's components is missing, they default to
700           00. So the time "12:30" and "12:30:00" are equivalent.
701
702           The "complete" method can be used to check what type of date was
703           parsed, and which values were specified (either explicitly or
704           implied) and which were provided as a default. It should be noted
705           that there is no way to differentiate between an explicit and
706           implied value.
707
708           A string with a date and/or time may consist of any of the
709           following:
710
711              a complete date and a time (complete or truncated)
712              a truncated date with no time
713              a time (complete or truncated) with no date
714
715           In other words, the date "Jan 2009 12:30" is not valid since it
716           consists of a time with a truncated date.
717

VALID TIME ZONE FORMATS

719       When specifying a time zone, it can be done in three different ways.
720       One way is to specify the actual time zone. The second is to supply a
721       valid time zone abbreviation. The third is to specify an offset (with
722       an optional abbreviation). The following dates illustrate the these
723       formats.
724
725       The timezone information always follows the time immediately, and may
726       only be included if a time is included. The following examples use an
727       ISO 8601 format for the date/time, but any of the other date and time
728       formats may be used.
729
730       The first way to specify the time zone is to specify it by complete
731       name (or using one of the standard aliases):
732
733          2001-07-01-00:00:00 America/New_York
734
735       Although this is unambiguous when it comes to determining the time
736       zone, the time is ambiguous in most zones for one hour of the year.
737       When a time change occurs during which the clock is moved back, the
738       same wall clock time occurs twice.
739
740       For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in
741       the morning, the clock was set back to 01:00. As a result, the date Nov
742       2, 2008 at 01:30 is ambiguous. It is impossible to determine if this
743       refers to the 01:30 that occurred half an hour before the time change,
744       or the one 30 minute after the change.
745
746       In practice, if this form is used, the date will be assigned to
747       standard time, meaning that there will be some times (typically 1 hour
748       per year) which cannot be expressed this way. As such, this method is
749       discouraged.
750
751       The second way to specify the time zone, which is the most common, is
752       to use a time zone abbreviation:
753
754          2001-07-01-00:00:00 EDT
755
756       Unfortunately, the abbreviation does not uniquely determine the time
757       zone except in a few cases. In order to assign a time zone, Date::Manip
758       will refer to a list of all time zones which use the abbreviation.
759       They will be tested, in the order given in the Date::Manip::Zones
760       documentation, and the first match (i.e. the one in which the given
761       date/time and abbreviation are valid) determines the time zone which
762       will be used. A great deal of effort has been made to ensure that the
763       most likely time zone will be obtained (i.e. the most common time zones
764       are tested before less common ones), so in most cases, the desired
765       results will be obtained.
766
767       If the default order does not yield the desired time zone, the order of
768       testing can be modified using the abbrev method described in the
769       Date::Manip::TZ documentation.
770
771       Although the time zone is ambiguous, the date is not, since only time
772       zones for which the date are valid will be used.
773
774       The third way to specify the time zone is by specifying an offset and
775       an optional abbreviation:
776
777          2001-07-01-00:00:00 -04
778          2001-07-01-00:00:00 -0400
779          2001-07-01-00:00:00 -040000
780          2001-07-01-00:00:00 -04:00
781          2001-07-01-00:00:00 -04:00:00
782
783          2001-07-01-00:00:00 -04 (EDT)
784          2001-07-01-00:00:00 -0400 (EDT)
785          2001-07-01-00:00:00 -040000 (EDT)
786          2001-07-01-00:00:00 -04:00 (EDT)
787          2001-07-01-00:00:00 -04:00:00 (EDT)
788
789          2001-07-01-00:00:00 -04 EDT
790          2001-07-01-00:00:00 -0400 EDT
791          2001-07-01-00:00:00 -040000 EDT
792          2001-07-01-00:00:00 -04:00 EDT
793          2001-07-01-00:00:00 -04:00:00 EDT
794
795       The offset almost never sufficient to uniquely determine the time zone
796       (and it is not even guaranteed that both the offset and abbreviation
797       will, though in practice, it is probably sufficient). In this instance,
798       the time zone will be determined by testing all time zones which have
799       the given offset (and abbreviation if it is included) until one is
800       found which matches both pieces of information. For more information
801       about how this testing is done, refer to the def_zone method of the
802       Date::Manip::TZ documentation.
803

VALID DATE FORMATS

805       There are several categories of date formats supported by Date::Manip.
806       These are strings which specify only the year/month/day fields.
807
808       These formats explicitly set the date, but not the time. These formats
809       may be combined with a time string (as specified below) to set both the
810       date and time. If this is not done, the default time is determined by
811       the DefaultTime config variable.
812
813       ISO 8601 dates
814           The preferred date formats are those specified by ISO 8601. The
815           specification includes valid calendar date and valid time formats.
816           Date::Manip will handle all of these formats, but does not require
817           that the dates rigidly adhere to the specification since the
818           ultimate goal of Date::Manip is to handle dates as they are
819           represented in real life and some common variations exist which are
820           similar to, but not identical to, those from the specification.
821
822           A calendar date includes the following fields:
823
824              CC    2-digit representation of the century
825              YY    2-digit representation of the year in
826                    a century
827              MM    2-digit representation of a month
828              DD    2-digit representation of a day of month
829              DoY   3-digit representation of a day of year
830                    (001-366)
831              Www   the character "W" followed by a 2-digit
832                    week of the year (01-53)
833              D     the day of the week (1-7)
834
835           The following date formats are considered complete by Date::Manip.
836           In the following, the date Thu Mar 5 2009 is used as an example.
837           This is the 64th day of the year. Thu is the 4th day of the week.
838           The week starting Mon, Mar 2 is the 10th week of the year
839           (according the the ISO 8601 definition). Obviously, some of the
840           formats are only valid when used at some times. For example, the
841           format --MMDD refers to a month and day in the current year, so the
842           date Mar 5, 2009 can only be specified using this format during
843           2009.
844
845              Format      Notes   Examples
846
847              CCYYMMDD            20090305
848              CCYY-MM-DD          2009-03-05
849
850              YYMMDD      1,2,4   090305
851              YY-MM-DD            09-03-05
852
853              -YYMMDD     3,4     -090305
854              -YY-MM-DD           -09-03-05
855
856              --MMDD      1       --0305
857              --MM-DD             --03-05
858
859              ---DD       1       ---05
860
861
862              CCYYDoY             2009064
863              CCYY-DoY            2009-064
864
865              YYDoY       1,4     09064
866              YY-DoY              09-064
867
868              -YYDoY      3,4     -09064
869              -YY-DoY             -09-064
870
871              -DoY        1       -064
872
873
874              CCYYWwwD            2009W104
875              CCYY-Www-D          2009-W10-4
876
877              YYWwwD      1,4     09W104
878              YY-Www-D            09-W10-4
879
880              -YYWwwD     3,4     -09W104
881              -YY-Www-D           -09-W10-4
882
883              -YWwwD      1       -9W104
884              -Y-Www-D            -9-W10-4
885                                  Y is the year (0-9) in
886                                  current decade
887
888              -WwwD       1       -W104
889              -Www-D              -W10-4
890
891              -W-D        1       -W-4
892                                  D is day (1-7) in
893                                  current week
894
895              ---D        1       ---4
896                                  same as -W-D
897
898           The following date formats are truncated:
899
900              CCYY-MM     2       2009-03   (2009-03-01)
901
902              CCYY                2009      (2009-01-01)
903
904              CC          2       20        (2000-01-01)
905
906              -YYMM       4       -0903
907              -YY-MM              -09-03
908
909              -YY         4       -09
910
911              --MM                --03
912
913              CCYYWww             2009W10
914              CCYY-Www            2009-W10
915
916              YYWww       4       09W10
917              YY-Www              09-W10
918
919              -YYWww      3,4     -09W10
920              -YY-Www             -09-W10
921
922              -Www                -W10
923
924           Notes:
925
926           1  These formats are considered truncated in the standard, but
927           since
928              they do include (or imply, using the current date for defaults)
929              all of the fields, and since they do not introduce any parsing
930              complexities, the standard is relaxed, and they are treated as
931              complete.
932
933           2  These formats are treated differently than in Date::Manip 5.xx
934           as
935              described below.
936
937           3  These formats are not defined in the ISO 8601 spec, but
938              are added for the sake of completeness since they do not
939              add any parsing incompatibilities.
940
941           4  Formats where the century is not given are described as a year
942           in
943              the current century in the specification. Date::Manip treats
944           this
945              more generically using the YYtoYYYY config variable. This will
946           be
947              used to determine how to determine the full year.
948
949           Date::Manip 5.xx handled ISO 8601 dates in a less rigid fashion,
950           and deviated from the specification in several formats. As of 6.00,
951           the specification is followed much more closely so that all of the
952           date formats included in it should produce valid dates.  This
953           changes, in a backwards incompatible way, the way a few strings
954           will be interpreted as dates.
955
956           As of 6.00, a two-digit date will be treated as CC. Previously, it
957           was treated as YY.
958
959           A six-digit date will be treated as YYMMDD. Previously, it was
960           treated as YYYYMM.
961
962           Previously, dashes were treated as optional in many cases.
963           According to the specification, dates may be written in expanded
964           form (with all dashes present) or abbreviate form (with no dashes).
965           As of 6.00, this is the behavior, so the formats: YYMMDD and YY-MM-
966           DD are allowed, as per the specification, but the format YY-MMDD is
967           NOT allowed (though it was previously).
968
969           The Www-D formats require a bit of explanation.  According to the
970           specification, the date:
971
972              1996-w02-3
973
974           refers to the day with an ordinal number of 3 within the calendar
975           week in the 2nd week of 1996.
976
977           In the specification, the days of the week are numbered from 1 to 7
978           (Monday to Sunday), and the week always begins on Monday, so day 1
979           (Monday) is always the first day of the week, day 2 (Tuesday) is
980           always the second day of the week, etc.
981
982           In Date::Manip, the constraint that the week must start with Monday
983           is relaxed, allowing the week to begin with Sunday (a far more
984           common start of the week in calendars, at least in some parts of
985           the world).
986
987           This presents a problem though in that the above date could be
988           interpreted as Wednesday (day 3) of the 2nd week of 1996, or as the
989           3rd day of the 2nd week of 1996 (which would normally be Wednesday,
990           but would be Tuesday if the week begins on Sunday).
991
992           As of Date::Manip 6.00, the above date will be interpreted as the
993           3rd day of the 2nd week. This is a reversal from Date::Manip 5.xx,
994           but I believe is what the specification would require. For more
995           information, refer to the Date::Manip::Changes document.
996
997       Common date formats
998           Date::Manip supports a number of common date formats. The following
999           fields may be included in a date:
1000
1001             YY    2-digit representation of the year
1002             YYYY  4-digit representation of the year
1003             M     1- or 2- digit representation of the month
1004             MM    2-digit representation of the month
1005             D     1- or 2- digit representation of the day
1006             DD    2-digit representation of the day
1007             mmm   The abbreviated or full month name (i.e. Jan)
1008
1009           The following date formats are supported:
1010
1011              Format      Notes   Examples
1012
1013              M/D         1,2,3   3/5
1014              M/D/YY      1       3/5/09
1015              M/D/YYYY    1       3/5/2009
1016
1017              YYYY/M/D            2009/3/5
1018
1019              mmm/D               Mar/5
1020              mmm/D/YY            Mar/5/09
1021              mmm/D/YYYY          Mar/5/2009
1022              D/mmm               5/Mar
1023              D/mmm/YY            5/Mar/09
1024              D/mmm/YYYY          5/Mar/2009
1025              YYYY/mmm/D          2009/Mar/5
1026
1027              mmmD                Mar5
1028              mmmDDYY     4       Mar0509
1029              mmmDDYYYY           Mar052009
1030              Dmmm                5Mar
1031              DmmmYY              5Mar09
1032              DmmmYYYY            5Mar2009
1033              YYYYmmmD            2009Mar5
1034
1035              mmmD YY             Mar5 09
1036              mmmD YYYY           Mar5 2009
1037              Dmmm YY             5Mar 09
1038              Dmmm YYYY           5Mar 2009
1039
1040              mmm/D YY            Mar/5 09
1041              mmm/D YYYY          Mar/5 2009
1042              D/mmm YY            5/Mar 09
1043              D/mmm YYYY          5/Mar 2009
1044
1045              YY   mmmD           09   Mar5
1046              YYYY mmmD           2009 Mar5
1047              YY   Dmmm           09   5Mar
1048              YYYY Dmmm           2009 5Mar
1049
1050              YY   mmm/D          09   Mar/5
1051              YYYY mmm/D          2009 Mar/5
1052              YY   D/mmm          09   5/Mar
1053              YYYY D/mmm          2009 5/Mar
1054
1055              YYYY:MM:DD          2010:01:15 (EXIF format)
1056
1057              mmmYYYY     4       Jun 2010
1058              YYYYmmm     4       2010 June
1059              mmm/YYYY    4       Jun/2010
1060              YYYY/mmm    4       2010/Jun
1061
1062           In the formats above, the slash (/) can be replace by any of the
1063           valid separators: whitespace, slash (/), period (.), or dash (-).
1064           The dash, though allowed, is discouraged since it may conflict with
1065           an ISO 8601 format.  For example, the format MM/DD/YY is just fine,
1066           but MM-DD-YY does not work since it conflicts with YY-MM-DD.  To be
1067           safe, if "-" is used as a separator in a non-ISO format, they
1068           should be turned into "/" before calling the Date::Manip routines
1069           or you should use the 'noiso8601' option with the parse or
1070           parse_date methods.
1071
1072           No matter what separator is used, the same separator must be used
1073           throughout the date. For example, MM/DD/YY is valid and MM.DD.YY is
1074           also valid, but MM/DD.YY is NOT valid.
1075
1076           Notes:
1077
1078           1  With these formats, Americans tend to write month first, but
1079           many
1080              other countries tend to write day first.  The latter behavior
1081           can be
1082              obtained by setting the config variable DateFormat to something
1083           other
1084              than "US".
1085
1086           2  The dot (.) separator may not be used in the M/D format since it
1087              will be interpreted as the H12,H+ format described below.
1088
1089           3  The M/D format should not use the period (.) separator as that
1090           will
1091              incorrectly match the HH,H+ time format.
1092
1093           4  Historically, I have not supported partial dates (i.e. dates
1094           that
1095              were not fully specified), but it has been argued that something
1096           like
1097              'Jun 1910' would be interpreted by almost everyone as a day in
1098           June
1099              of 1910 instead of June 19, 2010.  And it has been shown that in
1100              some applications, dates are specified in that way.  I have
1101           added the
1102              new config variable Format_MMMYYYY which will change this.  If
1103           this
1104              variable is not set, the formats allowed are:
1105
1106                 mmmDDYY
1107
1108              If it is set, the formats allowed are:
1109
1110                 mmmYYYY
1111                 YYYYmmm
1112
1113              The day of week may not be included with these formats.  When
1114              parsing a full date/time, if Format_MMMYYYY is set to 'first',
1115              it returns the 1st of the month at midnight.  If it is set to
1116              'last', it returns the last day at 23:59:59.  If parsing only
1117              only a date, it will be set to the first or last day of the
1118              month at midnight.
1119
1120           These formats explicitly set the date, but not the time. The
1121           default time is determined by the DefaultTime config variable.
1122
1123       Less common date formats
1124           The following formats are also supported by Date::Manip:
1125
1126              DoW
1127                   The day of week of the current week
1128                      Friday
1129                      Friday at 12:40
1130
1131              MMM Nth [YYYY]
1132              Nth MMM [YYYY]
1133              YYYY MMM Nth
1134              YYYY Nth MMM
1135                   Dec 1st 1970
1136                   1st Dec 1970
1137                   1970 Dec 1st
1138                   1970 1st Dec
1139
1140              next/prev DoW
1141                   The next or last occurrence of DoW
1142                      next Friday
1143                      last Friday at 12:40
1144
1145              next/last week/month/year
1146                   The day one week/month/year from now
1147                   or in the past
1148                      next week
1149                      last month at 15:00
1150
1151              last day in MMM [YYYY]
1152                   The last day of the month
1153                      last day in October
1154                      last day in October 1996
1155
1156              last DoW in MMM [YYYY]
1157                   The last DoW in the month
1158                      last Tuesday in October
1159                      last Tuesday in October 1996
1160
1161              last DoW in YYYY
1162                   The last DoW in the year
1163                      last Tuesday in 1997
1164
1165                      NOTE: "last DoW" doesn't work in
1166                      English since the word "last"
1167                      is used for both this expression
1168                      and for "prev DoW", which gets
1169                      parsed first. "last DoW" MAY
1170                      work in other languages.
1171
1172              Nth DoW in MMM [YYYY]
1173                   The Nth DoW in the month
1174                      3rd Tuesday in October
1175                      3rd Tuesday in October 1996
1176
1177              Nth DoW [YYYY]
1178                   The Nth DoW in the year
1179                      22nd Sunday
1180                      22nd Sunday in 1996
1181
1182              Nth day in MMM [YYYY]
1183                   The Nth day of the month
1184                      1st day of February
1185                      1st day of February 2012
1186
1187              DoW week
1188                   British: same as "in 1 week on DoW"
1189                      Monday week
1190
1191              DoW week N [YYYY]
1192              Dow Nth week [YYYY]
1193                   Sunday week 22
1194                   Sunday 22nd week
1195                      These refer to the day of week
1196                      of the Nth week of the year.
1197
1198              Nth
1199                   12th
1200                      This refers to the Nth day of the
1201                      current month.
1202
1203           Note that the formats "Sunday week 22" and "22nd Sunday" give
1204           different behaviors.  "Sunday week 22" returns the Sunday of the
1205           22nd week of the year based on how week 1 is defined.  ISO 8601
1206           defines week one to contain Jan 4, so "Sunday week 1" might be the
1207           first or second Sunday of the current year, or the last Sunday of
1208           the previous year.  "22nd Sunday" gives the actual 22nd time Sunday
1209           occurs in a given year, regardless of the definition of a week.
1210
1211       Special date strings
1212           Most languages have strings which can be used to specify the date
1213           (relative to today). In English, these include the strings:
1214
1215              today
1216              tomorrow
1217              yesterday
1218
1219           There is also support for the British formats:
1220
1221              today week
1222              tomorrow week
1223              yesterday week
1224
1225           which refer to one week after today/tomorrow/yesterday
1226           respectively.
1227
1228           Other languages have similar strings.
1229
1230       Holidays
1231           You can parse holiday names as dates (including timezones).  For
1232           example:
1233
1234              Christmas
1235              Christmas 2010
1236              Christmas 2010 at noon
1237              Christmas 2010 at noon PST
1238              Saturday Christmas 2010 at noon
1239
1240       In all of the formats (except for ISO 8601 formats), the day of week
1241       ("Friday") can be entered anywhere in the date and it will be checked
1242       for accuracy.  In other words,
1243
1244         "Tue Jul 16 1996 13:17:00"
1245
1246       will work but
1247
1248         "Jul 16 1996 Wednesday 13:17:00"
1249
1250       will not (because Jul 16, 1996 is Tuesday, not Wednesday).
1251

A NOTE ABOUT FOREIGN LANGUAGE DATES

1253       Although Date::Manip has some support for parsing dates in foreign
1254       languages, it must be noted that the formats supported are largely
1255       based on English equivalents.
1256
1257       There are probably many different dates that are perfectly valid, and
1258       in common usage, in other languages which do not have an equivalent in
1259       the English language, and unfortunately, Date::Manip will probably not
1260       parse these.
1261
1262       You are free to send these to me, and I'll see if there is a way to add
1263       them in, but I do not guarantee anything.  Without having a full-blown
1264       language parser (or at least the portion of the language that is
1265       devoted to calendar and time), most of these formats will simply not be
1266       supportable.
1267

VALID TIME FORMATS

1269       There are several categories of time formats supported by Date::Manip.
1270       These are strings which specify only the hour/minute/second fields.
1271
1272       ISO 8601 times
1273           A time may be also be complete or truncated.  Again, Date::Manip
1274           treats some formats as complete even though the specification calls
1275           them truncated.
1276
1277           A time may include the following fields:
1278
1279              HH    2-digit representation of the hour
1280              MN    2-digit representation of the minutes
1281              SS    2-digit representation of the seconds
1282              H+    1+ digit representation of fractional hours
1283              M+    1+ digit representation of fractional minutes
1284              S+    1+ digit representation of fractional seconds
1285
1286           The following time formats are considered complete by Date::Manip.
1287           The time 12:30:15 will be expressed in the examples.
1288
1289              Format      Notes   Examples
1290
1291              HHMNSS      2       123015
1292
1293              HH:MN:SS            12:30:15
1294
1295              HHMNSS,S+           123015,5
1296              HH:MN:SS,S+         12:30:15,5
1297                                  Fractional seconds are ignored
1298
1299              HHMN,M+             1230,25
1300              HH:MN,M+            12:30,25
1301                                  This is 12:30:00 + 0.25 minutes
1302
1303              HH,H+               12,5
1304                                  This is 12:00:00 + 0.5 hours, so
1305                                  this is equivalent to 12:30:00
1306
1307              -MNSS       1       -3015
1308              -MN:SS              -30:15
1309
1310              --SS        1       --15
1311
1312              -MNSS,S+    1       -3015,5
1313              -MN:SS,S+           -30:15,5
1314
1315              -MN,M+      1       -30,25
1316
1317              --SS,S+     1       --15,5
1318
1319              HHMN        3       1230
1320              HH:MN               12:30
1321
1322           The following time formats are truncated:
1323
1324              HH                  12
1325
1326              -MN                 -30
1327
1328           Notes:
1329
1330           1  These formats are considered truncated in the standard, but
1331           since
1332              they do include (or imply, using the current time for defaults)
1333           all of
1334              the fields, and since they do not introduce any parsing
1335           complexities,
1336              the standard is relaxed, and they are treated as complete.
1337
1338           2  The HHMNSS format will not be correctly parsed since it is
1339           impossible
1340              to distinguish between it and YYMMDD. In order to parse an all-
1341           digit
1342              time, add the string ",0" to the end to force it to be
1343           interpreted
1344              as a time or include time zone information (either a zone name
1345           or
1346              abbreviation... an offset will not work in this case).
1347
1348           3  The HH:MN format will be treated as complete, even though it is
1349              incomplete due to missing the seconds. In real life, expressing
1350              a time in the HH:MN format is very common, and is regarded as
1351           complete,
1352              and might include time zone information.
1353
1354           ISO 8601 times may be followed by a time zone unless they are
1355           truncated.  Truncated times may not include a timezone.
1356           Date::Manip relaxes the constraints placed on the time zone format
1357           and allows any of the methods used to specify the time zone
1358           including time zone name, abbreviation, or offset. The time zone
1359           may be separated from the time by a space, but it is not required.
1360
1361           Another constraint that is relaxed is that the fractional part may
1362           be specified using a period. In other words, the following are
1363           equivalent:
1364
1365              12:30,25
1366              12:30.25
1367
1368           It should be noted (as it is in the specification) that using a
1369           negative time zone offset may cause confusion. In addition to
1370           visually confusing, it may not be parsed correctly. For example,
1371           the time:
1372
1373              123005-0300
1374
1375           may not be parsed correctly. When using an offset time zone, you
1376           should always use the colon separators in the time:
1377
1378              12:30:05-0300
1379
1380       Other time formats
1381           A time may include any of the following fields:
1382
1383              H24   1- or 2-digit representation of the hour (0-23)
1384              H12   1- or 2-digit representation of the hour (1-12)
1385              MN    2-digit representation of the minutes
1386              SS    2-digit representation of the seconds
1387              H+    1+ digit representation of fractional hours
1388              M+    1+ digit representation of fractional minutes
1389              S+    1+ digit representation of fractional seconds
1390              AM    A language specific AM/PM string
1391
1392           The following time formats are accepted:
1393
1394              Format              Examples
1395
1396              H24:MN:SS           17:30:15
1397              H12:MN:SS AM        5:30:15 PM
1398              H12:MN:SS
1399
1400              H24:MN:SS,S+        17:30:15,5
1401              H12:MN:SS,S+ AM     5:30:15,5 PM
1402              H12:MN:SS,S+        Fractional seconds are ignored
1403
1404              H24:MN,M+           17:30,25
1405              H12:MN,M+ AM        5:30,25 PM
1406              H12:MN,M+           This is 17:30:00 + 0.25 minutes
1407
1408              H24,H+              17,5
1409              H12,H+ AM           5,5 PM
1410              H12,H+              This is 17:00:00 + 0.5 hours, so
1411                                  this is equivalent to 17:30:00
1412
1413              H24:MN              17:30
1414              H12:MN AM           5:30 PM
1415              H12:MN
1416
1417              H12 AM              5 PM
1418
1419           The fractional part may be specified using a comma or a period.
1420           Fractional seconds may also be separated using a colon.  A language
1421           specific fractional separator may also be available for some
1422           languages.
1423
1424           In other words, the following are equivalent:
1425
1426              12:30:20,25
1427              12:30:20.25
1428              12:30:20:25
1429
1430           Some languages have alternate H:MN and MN:S separators. For
1431           example, one H:MN separator in French is 'h' (the MN:S separator is
1432           still a colon), so the following are equivalent:
1433
1434              12:30:00
1435              12h30:00
1436
1437           Time zone information can be included immediately following the
1438           time.  It can be separated by whitespace from the time, or it can
1439           be immediately adjacent.
1440
1441       Special time strings
1442           Different languages may have some words which can be used to
1443           specify a certain time of day. In English, for example, the
1444           following words are equivalent to the time listed:
1445
1446              noon        12:00:00
1447              midnight    00:00:00
1448
1449           So, the following are equivalent:
1450
1451              Jan 2 2009 at noon
1452              Jan 2 2009 12:00:00
1453
1454           There were two possible ways to interpret midnight. One was at the
1455           start of the day (00:00:00) and the other was at the end of the day
1456           (24:00:00 which would actually mean at 00:00:00 of the following
1457           day).  The first has been used to maintain backwards compatibility
1458           with Date::Manip 5.xx .
1459
1460           Other languages have similar strings.
1461
1462       In most languages, a word similar to "at" may precede the time (this
1463       does NOT apply to ISO 8601 time formats). This word (which must be
1464       separate from all other parts of the date with whitespace) is optional,
1465       and the following are equivalent:
1466
1467          12:30
1468          at 12:30
1469
1470       The times "12:00 am", "12:00 pm", and "midnight" are not well defined.
1471       Date::Manip uses the following convention:
1472
1473         midnight = 12:00am = 00:00:00
1474         noon     = 12:00pm = 12:00:00
1475
1476       and the day goes from 00:00:00 to 23:59:59.  In other words, midnight
1477       is the beginning of a day rather than the end of one.  The time
1478       24:00:00 is also allowed (though it is automatically transformed to
1479       00:00:00 of the following day). This gives the unusual result of
1480       parsing:
1481
1482         Wed Feb 8 2006 24:00:00
1483
1484       which gives the date of:
1485
1486         Thu Feb 9 2006 00:00:00
1487

VALID COMBINED DATE AND TIME FORMATS

1489       There are several categories of strings which specify both the date and
1490       time. These include the following:
1491
1492       ISO 8601 combined date and time
1493           A combined ISO 8601 date and time is a string containing a complete
1494           ISO 8601 date and a complete or truncated ISO 8601 time.  It may
1495           also include a timezone, provided a complete time is included.
1496
1497           Date::Manip relaxes the restrictions on how the two are combined.
1498           The time may be separated from the date by space, dash, or the
1499           letter T, or the two may be joined with nothing separating them.
1500
1501           When the time immediately follows the date, or when the two are
1502           separated by a dash, the resulting string MUST be unambiguous.
1503           Provided the date includes all of the dashes in it (i.e. YY-MM-DD
1504           instead of YYMMDD), it is rare that there is any ambiguity. If the
1505           date does not include dashes, the strings may be ambiguous, and in
1506           this case, separating the date and time with a space or the letter
1507           T is useful (and perhaps necessary) to correctly interpret the
1508           string.
1509
1510           The DoY formats should always be separated from the time by
1511           something. They are visually confusing if they are not separated
1512           from the time.
1513
1514           Time zone information can be included immediately following a
1515           complete time.  It may not be included if no time is given, or if a
1516           truncated time is included. The time zone may be separated from the
1517           time with whitespace, or it can be immediately adjacent to it
1518           (since the ISO 8601 specification allows it in some cases).
1519
1520       Non-ISO 8601 combined date and time
1521           A date from any of the non-ISO 8601 formats above may be combined
1522           with any of the non-ISO 8601 time formats above in any combination
1523           to form a valid combined date and time.
1524
1525       Deltas
1526           Dates are often specified in terms of a delta from "now". For
1527           example, "in 2 days".
1528
1529           Most valid deltas can be used to specify a date, and the date is
1530           defined as that delta added to "now". Refer to the
1531           Date::Manip::Delta documentation for a list of valid delta formats.
1532
1533           If the delta itself does not include a time part, the time may be
1534           specified explicitly. For example:
1535
1536              in 3 days at 12:00:00
1537              in 3 days at 12:00:00 PST
1538
1539           will take the delta part "in 3 days" and add it to the current
1540           time, then set the time to 12:00:00.
1541
1542           It is NOT allowed to include an explicit time if any time segment
1543           was included in the delta. For example, the following is invalid:
1544
1545              in 3 days 2 hours at 12:00:00
1546
1547           One additional format that is supported is to include only week (or
1548           higher) components in the delta and to set the day of week. For
1549           example:
1550
1551             Friday in 2 weeks
1552             in 2 weeks on Friday
1553             Friday 2 weeks ago
1554             2 weeks ago on Friday at 13:45
1555
1556           These first apply the delta (of weeks, months, and years) to the
1557           current time, and then set the day to the given day-of-week in that
1558           week.
1559
1560       Special date and time strings
1561           Most language have strings which can be used to specify the full
1562           date and time (relative to the current date and time). In English,
1563           these include the string:
1564
1565              now
1566
1567           They may also have a timezone attached:
1568
1569              now PST
1570
1571       Additional combined date and time formats
1572           The following formats are also supported:
1573
1574              epoch SECS
1575                 The number of seconds since the epoch
1576                 (Jan 1, 1970 00:00:00 GMT). SECS may
1577                 be negative to give time before the
1578                 epoch.
1579
1580           or
1581
1582              epoch SECS TIMEZONE
1583
1584       A couple of notes:
1585
1586       Commas may be included in all date formats arbitrarily (except for ISO
1587       8601 formats where they may only be included when allowed by the
1588       specification).
1589
1590       The time/time zone is removed from the date before the date is parsed,
1591       so the time may appear before or after the date, or between any two
1592       parts of the date.
1593
1594       The time and the zone do not need to be adjacent, so the string:
1595
1596          Jan 21 17:13:27 2010 -0400
1597
1598       will work.  If the timezone is separate from the date, it MUST be
1599       separated from any other portion of the date by whitespace.
1600
1601       Certain words such as "on", "in", "at", "of", etc. which commonly
1602       appear in a date or time are ignored (except in ISO 8601 formats).
1603

PRINTF DIRECTIVES

1605       The following printf directives are replaced with information from the
1606       date.
1607
1608          Year
1609              %y     year                     - 00 to 99
1610              %Y     year                     - 0001 to 9999
1611
1612          Month, Week
1613              %m     month of year            - 01 to 12
1614              %f     month of year            - " 1" to "12"
1615              %b,%h  month abbreviation       - Jan to Dec
1616              %B     month name               - January to December
1617
1618          Day
1619              %j     day of the year          - 001 to 366
1620              %d     day of month             - 01 to 31
1621              %e     day of month             - " 1" to "31"
1622              %v     weekday abbreviation     - " S"," M"," T", ...
1623              %a     weekday abbreviation     - Sun to Sat
1624              %A     weekday name             - Sunday to Saturday
1625              %w     day of week              - 1 to 7 (1=Monday)
1626              %E     day of month with
1627                     suffix                   - 1st, 2nd, 3rd...
1628
1629          Hour
1630              %H     hour                     - 00 to 23
1631              %k     hour                     - " 0" to "23"
1632              %i     hour                     - " 1" to "12"
1633              %I     hour                     - 01 to 12
1634              %p     AM or PM
1635
1636          Minute, Second, Time zone
1637              %M     minute                   - 00 to 59
1638              %S     second                   - 00 to 59
1639              %Z     time zone abbreviation   - EDT
1640              %z     time zone as GMT offset  - +0100 (see Note 4)
1641              %N     time zone as GMT offset  - +01:00:00
1642
1643          Epoch (see NOTE 3 below)
1644              %s     seconds from
1645                     1/1/1970 GMT             - negative if before
1646              %o     seconds from 1/1/1970
1647                     in the current time
1648                     zone
1649
1650          Date, Time
1651              %c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995
1652              %C,%u  %a %b %e %H:%M:%S %Z %Y  - Fri Apr 28 17:25:57 EDT 1995
1653              %g     %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT
1654              %D     %m/%d/%y                 - 04/28/95
1655              %x     %m/%d/%y or %d/%m/%y     - 04/28/95 or 28/04/95
1656                                                (Depends on DateFormat variable)
1657              %l     date in ls(1) format (see NOTE 1 below)
1658                       %b %e %H:%M            - Apr 28 17:23 (*)
1659                       %b %e  %Y              - Apr 28  1993 (*)
1660              %r     %I:%M:%S %p              - 05:39:55 PM
1661              %R     %H:%M                    - 17:40
1662              %T,%X  %H:%M:%S                 - 17:40:58
1663              %V     %m%d%H%M%y               - 0428174095
1664              %Q     %Y%m%d                   - 19961025
1665              %q     %Y%m%d%H%M%S             - 19961025174058
1666              %P     %Y%m%d%H:%M:%S           - 1996102517:40:58
1667              %O     %Y-%m-%dT%H:%M:%S        - 1996-10-25T17:40:58
1668              %F     %A, %B %e, %Y            - Sunday, January  1, 1996
1669              %K     %Y-%j                    - 1997-045
1670
1671          Special Year/Week formats (see NOTE 2 below)
1672              %G     year, Monday as first
1673                     day of week              - 0001 to 9999
1674              %W     week of year, Monday
1675                     as first day of week     - 01 to 53
1676              %L     year, Sunday as first
1677                     day of week              - 0001 to 9999
1678              %U     week of year, Sunday
1679                     as first day of week     - 01 to 53
1680              %J     %G-W%W-%w                - 1997-W02-2
1681
1682          Other formats
1683              %n     insert a newline character
1684              %t     insert a tab character
1685              %%     insert a `%' character
1686              %+     insert a `+' character
1687
1688          All other characters are currently unused, but may be used in the
1689          future.  They currently insert the character following the %.
1690
1691          The following multi-character formats also exist:
1692
1693          Extended formats
1694              %<A=NUM>   These returns the NUMth value of the %A, %a, and %v formats
1695              %<a=NUM>   respectively.  In English, that would yield:
1696              %<v=NUM>      %<A=2>   => Tuesday
1697                            %<a=2>   => Tue
1698                            %<v=2>   => T
1699                         NUM must be in the range 1-7.
1700
1701              %<B=NUM>   These return the NUMth value of the %B and %b formats
1702              %<b=NUM>   respectively.  In English, that would yield:
1703                            %<B=2>   => February
1704                            %<b=2>   => Feb
1705                         NUM must be in the range 1-12 (or 01-12).
1706
1707              %<p=NUM>   These return the NUMth value of the %p format.  In
1708                         English, that would yield:
1709                            %<p=1>   => AM
1710                            %<p=2>   => PM
1711                         NUM must be in the range 1-2.
1712
1713              %<E=NUM>   These return the NUMth value of the %E format.  In
1714                         English, that would yield:
1715                            %<E=1>   => 1st
1716                            %<E=53>  => 53rd
1717                         NUM must be in the range 1-53.
1718
1719       If a lone percent is the final character in a format, it is ignored.
1720
1721       The formats used in this routine were originally based on date.pl
1722       (version 3.2) by Terry McGonigal, as well as a couple taken from
1723       different versions of the Solaris date(1) command.  Also, several have
1724       been added which are unique to Date::Manip.
1725
1726       NOTE 1:
1727
1728       The ls format (%l) applies to date within the past OR future 6 months!
1729       Any date that is before the date NOW - 6 months, or that is on or after
1730       the date NOW + 6 months will have the year printed out.
1731
1732       The later time must be on or after so that there is no ambiguity. If it
1733       is now 2000-06-06-12:00:00, then the date 1999-12-06-12:00:00 will be
1734       written as "Dec 6 12:00" but the date 2000-12-06-12:00:00 will be
1735       written as "Dec 6 2000".
1736
1737       NOTE 2:
1738
1739       The %U, %W, %L, %G, and %J formats are used to support the ISO-8601
1740       format: YYYY-wWW-D.  In this format, a date is written as a year, the
1741       week of the year, and the day of the week.  Technically, the week may
1742       be considered to start on any day of the week, but Sunday and Monday
1743       are the both common choices, so both are supported.
1744
1745       The %W and %G formats return the week-of-year and the year treating
1746       weeks as starting on Monday.
1747
1748       The %U and %L formats return the week-of-year and the year treating
1749       weeks as starting on Sunday.
1750
1751       Most of the time, the %L and %G formats returns the same value as the
1752       %Y format, but there is a problem with days occurring in the first or
1753       last week of the year.
1754
1755       The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D
1756       format is actually 1992-W53-5.  In other words, Jan 1 is treated as
1757       being in the last week of the preceding year.  Depending on the year,
1758       days in the first week of a year may belong to the previous year, and
1759       days in the final week of a year may belong to the next year.  The week
1760       is assigned to the year which has most of the days.  For example, if
1761       the week starts on Sunday, then the last week of 2003 is 2003-12-28 to
1762       2004-01-03.  This week is assigned to 2003 since 4 of the days in it
1763       are in 2003 and only 3 of them are in 2004.  The first week of 2004
1764       starts on 2004-01-04.
1765
1766       The %U and %W formats return a week-of-year number from 01 to 53. %L
1767       and %G return the corresponding year, and to get this type of
1768       information, you should always use the (%W,%G) combination or (%U,%L)
1769       combination. %Y should not be used as it will yield incorrect results.
1770
1771       %J returns the full ISO-8601 format (%G-W%W-%w).
1772
1773       NOTE 3:
1774
1775       The %s and %o formats return negative values if the date is before the
1776       start of the epoch.  Other Unix utilities would return an error, or a
1777       zero, so if you are going to use Date::Manip in conjunction with these,
1778       be sure to check for a negative value.
1779
1780       NOTE 4:
1781
1782       The %z format returns the offset in the RFC 822 specified format +0500
1783       .  Most offsets are full hour amounts, so this is not a problem, but
1784       some offsets are irregular (+05:17:30). In this case, the string
1785       returned is +051730 which isn't RFC 822 compliant, but since RFC 822
1786       ignores this situation, I had to decide between returning an incorrect
1787       value, or breaking strict compliance, and I chose the second option.
1788

KNOWN BUGS

1790       None known.
1791

BUGS AND QUESTIONS

1793       Please refer to the Date::Manip::Problems documentation for information
1794       on submitting bug reports or questions to the author.
1795

SEE ALSO

1797       Date::Manip        - main module documentation
1798

LICENSE

1800       This script is free software; you can redistribute it and/or modify it
1801       under the same terms as Perl itself.
1802

AUTHOR

1804       Sullivan Beck (sbeck@cpan.org)
1805
1806
1807
1808perl v5.28.2                      2019-02-28              Date::Manip::Date(3)
Impressum