1Date::Manip::Date(3) User Contributed Perl Documentation Date::Manip::Date(3)
2
3
4
6 Date::Manip::Date - Methods for working with dates
7
9 use Date::Manip::Date;
10 $date = new Date::Manip::Date;
11
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
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.
109
110 list_events
111 @list = $date->list_events( [$format] );
112 @list = $date->list_events(0 [,$format]);
113 @list = $date->list_events($date1 [,$format]);
114
115 This returns a list of events. Events are defined in the Events
116 section of the config file (discussed in the Date::Manip::Holidays
117 manual).
118
119 In the first form, a list of all events active at the precise time
120 stored in $date will be returned.
121
122 If the first argument evaluates to 0, a list of all events active
123 at any time during that day (Y,M,D) are returned.
124
125 If the first argument is another date object, all events that are
126 active at any time between the two dates (inclusive) are returned.
127
128 By default, the list returned is of the form:
129
130 ( [START, END, NAME],
131 [START, END, NAME],
132 ...
133 )
134
135 where START is a date object when an event starts, END is a date
136 object when it ends, and NAME is the name of the event. Note that
137 START and END are the actual start and end date of the event and
138 may be outside the range of dates being examined (though the event
139 will obviously overlap the range or it wouldn't be included in the
140 list).
141
142 If $format is included, it can specify an alternate format for the
143 output. Currently, the only supported format is named "dates" and
144 it returns a list in the form:
145
146 ( [DATE1, NAME1a, NAME1b, ...],
147 [DATE2, NAME2a, NAME2b, ...],
148 ...
149 )
150
151 This includes a list of all dates during the range when there is a
152 change in what events are active. DATE1 will always be the start of
153 the range being considered, and (NAME1a, NAME1b, ...) are the list
154 of all events that will be active at that time. At DATE2, the list
155 of active events changes with (NAME2a, NAME2b, ...) being active.
156
157 It is quite possible that a date be included which has no active
158 events, and in that case, the list of names will be empty.
159
160 nearest_business_day
161 $date->nearest_business_day([$tomorrowfirst]);
162
163 This looks for the work day nearest to $date. If $date is a work
164 day, it is left unmodified. Otherwise, it will look forward or
165 backwards in time 1 day at a time until a work day is found. If
166 $tomorrowfirst is non-zero (or if it is omitted and the config
167 variable TomorrowFirst is non-zero), we look to the future first.
168 Otherwise, we look in the past first. In other words, in a normal
169 week, if $date is Wednesday, $date is returned. If $date is
170 Saturday, Friday is returned. If $date is Sunday, Monday is
171 returned. If Wednesday is a holiday, Thursday is returned if
172 $tomorrowfirst is non-nil or Tuesday otherwise.
173
174 next_business_day
175 prev_business_day
176 $date->next_business_day($off [,$checktime]);
177 $date->prev_business_day($off [,$checktime]);
178
179 The next_business_day method sets the given date to $off (which can
180 be a positive integer or zero) business days in the future. The
181 prev_business_day method sets the date to $off business days in the
182 past.
183
184 First, $date is tested. If $checktime is nonzero, the date must
185 fall on a business date, and during business hours. If $checktime
186 is zero, the time check is not done, and the date must simply fall
187 on a business date.
188
189 If the check fails, the date is moved to the start of the next
190 business day (if $checktime is nonzero) or the next business day at
191 the current time (if $checktime is zero). Otherwise, it is left
192 unmodified.
193
194 Next, if $off is greater than 0, the day $off work days from now is
195 determined.
196
197 One thing to note for the prev_business_day method is that if $date
198 check fails, the date is set to the next business date, exactly
199 like next_business_day. In other words, if $date is not a business
200 day, the call:
201
202 $date->prev_business_day(0 [,$checktime]);
203
204 moves $date forward in time instead of backward which is
205 nonintuitive, but you just have to think of day 0 as being the next
206 business day if $date is not a business day.
207
208 As a result, the following two calls ALWAYS give the same result:
209
210 $date->next_business_day(0 [,$checktime]);
211 $date->prev_business_day(0 [,$checktime]);
212
213 no matter what date is stored in $date.
214
215 parse
216 $err = $date->parse($string [,@opts]);
217
218 This parses a string which should include a valid date and stores
219 it in the object. If the string does not include a valid date, an
220 error is returned. Use the err method to see the full error
221 message.
222
223 A full date may include a calendar date (year, month, day), a time
224 of day (hour, minute, second), and time zone information. All of
225 this can be entered in many different formats.
226
227 For information on valid date formats, refer to the section VALID
228 DATE FORMATS. For information on valid time zone information, refer
229 to the section VALID TIME ZONE FORMATS.
230
231 If no time zone information is included in the date, it is treated
232 as being in the local time zone.
233
234 If time zone information is included, the date will be kept in that
235 time zone, and all operations will be done in that time zone. The
236 convert method can be used to change the time zone to the local
237 time zone, or to another time zone.
238
239 Some things to note:
240
241 All strings are case insensitive. "December" and "DEceMBer" are
242 equivalent.
243
244 When a part of the date is not given, defaults are used. This is
245 described below in the section "Complete vs. truncated dates and
246 times".
247
248 The year may be entered as 2 or 4 digits. If entered as 2 digits,
249 it will be converted to a 4 digit year. There are several ways to
250 do this based on the value of the YYtoYYYY config variable. Refer
251 to the Date::Manip::Config documentation for more details.
252
253 Dates are always checked to make sure they are valid.
254
255 If any other arguments are passed in, they act as options which may
256 improve the speed of parsing. These include:
257
258 noiso8601 Do not try to parse the
259 date as an ISO 8601 date
260 or time.
261 nodow Do not try to parse a
262 day-of-week (Monday) in
263 the string.
264 nocommon Do not try to parse the
265 date using the formats
266 in the "Common date
267 formats" section.
268 noother Do not try to parse the
269 date using the "Less common
270 date formats" or a time
271 using the "Other time
272 formats".
273 nospecial Do not try to parse the
274 date using the "Special
275 date strings" formats
276 or a time using the
277 "Special time strings"
278 formats, or as a
279 combined date/time using
280 the "Additional combined
281 date and time" formats.
282 nodelta Do not treat deltas as
283 a date relative to now.
284 noholidays Do not parse holiday
285 names as dates.
286
287 parse_date
288 $err = $date->parse_date($string [,@opts]);
289
290 This parses a string which contains a valid date and sets the date
291 part of the object.
292
293 If the object contained a valid date, the time is kept unchanged.
294 If the object did NOT contain a valid date, a time of 00:00:00 is
295 used.
296
297 @opts can be any of the strings described in the parse method
298 above.
299
300 parse_time
301 $err = $date->parse_time($string [,@opts]);
302
303 This parses a string and sets the time portion of $date to contain
304 it.
305
306 If the object contained a valid date, the Y/M/D portion is left
307 unchanged. Otherwise, the current date is used.
308
309 @opts can be 'noiso8601' or 'noother'.
310
311 parse_format
312 $err = $date->parse_format($format,$string);
313 ($err,%match) = $date->parse_format($format,$string);
314
315 This will parse a date contained in $string based on explicit
316 format information contained in $format.
317
318 If the format is invalid, $err will contain an error message. If
319 the format is valid, but string doesn't match, an error code of 1
320 is returned.
321
322 If called in array context, a hash will be returned containing %+.
323 This is primarily useful if the $format string contains some named
324 capture groups that you define. This is discussed below.
325
326 $format is a string containing a regular expression with some
327 special directives (based on the printf directives). These
328 directives are turned into regular expression components, and then
329 the entire string is turned into a regular expression which, if
330 $string matches it, will return the date.
331
332 The directives available are identical to the printf directives.
333 So, if your $format string contains the directive '%Y', it will
334 match a 4-digit year.
335
336 All of the printf directives are available here with a few caveats:
337
338 %l This directive is NOT available.
339
340 %b,%h,%B These will all match a month name or abbreviation.
341
342 %v,%a,%A These will all match a day name or abbreviation.
343
344 %z,%Z,%N These will match any time zone string.
345
346 %n Multi-line matching is not currently supported,
347 so this directive is not allowed.
348
349 %x All format directives are converted to a regular
350 expression and then cached (so that a format
351 can be reused without the penalty of doing the
352 conversion to a regular expression with each use).
353 As a result, if you need to set the DateFormat config
354 variable (which determines the meaning of the %x
355 directive), it must be done before a format string
356 containing %x is used. If the DateFormat config variable
357 is set afterwards, the format string will reflect the
358 old, NOT THE NEW, value of DateFormat.
359
360 The format string may not over-specify the date. In other words,
361 you may not include both a %y and %Y directive or both a %j and %m
362 directive.
363
364 A valid format string will specify any of the following sets of
365 data:
366
367 Required Optional
368
369 M D H Mn S Y Zone Day-of-week
370 M D H Mn Y Zone Day-of-week
371 M D Y Zone Day-of-week
372 H Mn S Zone
373 H Mn Zone
374
375 For example, if you had a date stored as:
376
377 YYYY.MM-DD
378
379 you could match it using the following:
380
381 $date->parse_format('%Y\\.%m\\-%d',$string);
382
383 If you wanted to extract the date from an apache log line:
384
385 10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] "GET /favicon.ico ...
386
387 you could use:
388
389 $date->parse_format('.*?\\[%d/%b/%Y:%T %z\\].*',$line);
390
391 When matching months, days, and hours, there are two directives
392 that could be used (for numerical versions). For the month, you
393 may use %m or %f. If your date is known to have a two-digit month,
394 you should use %m. If it contains a one- or two-digit month, you
395 must use %f (and it is safe to use %f for two-digit months).
396 Similarly, for days, you can use %d or %e and for hours you can use
397 %H or %k. In both cases, the first can only be used if you are
398 guaranteed a 2-digit value.
399
400 In your format string, you may use capture groups (or back
401 references to them) in the regular expression using all of the
402 rules of normal regular expressions. Since Date::Manip uses named
403 capture groups internally, it is suggested that you also use named
404 groups. Mixing numbered and named groups will work... but it'll be
405 entirely up to you to keep track of what numbers refer to which
406 capture groups.
407
408 Every printf directive adds one or more named capture groups to the
409 regular expression. If you use named groups in the format string,
410 they must not conflict with the ones used internally, or else the
411 date will probably not be parsed correctly.
412
413 The following named capture groups are used internally:
414
415 y
416 m
417 d
418 h
419 mn
420 s
421 mon_name
422 mon_abb
423 dow_name
424 dow_abb
425 dow_char
426 dow_num
427 doy
428 nth
429 ampm
430 epochs
431 epocho
432 tzstring
433 off
434 abb
435 zone
436 g
437 w
438 l
439 u
440
441 To be safe, it is suggested that any additional named capture
442 groups introduced by the programmer start with a capital letter.
443 This is guaranteed to never conflict with any existing, or future
444 named capture groups.
445
446 In order to get access to the values stored in the additional named
447 capture groups, the parse_format function must be called in list
448 context, and the %+ array will be returned as the second value.
449
450 As an example:
451
452 $string = "before 2014-01-25 after";
453 ($err,%m) = $date->parse_format('(?<PRE>.*?)%Y-%m-%d(?<POST>.*)',$string);
454
455 would return a hash (%m) with the following key/value pairs:
456
457 'PRE' => 'before '
458 'POST' => ' after'
459
460 prev
461 next
462 The prev method changes the date to the previous (or current)
463 occurrence of either a day of the week, a certain time of day, or
464 both. The next method changes the date to the next (or current)
465 occurrence. The examples below illustrate the prev method, but the
466 next one is identical in operation.
467
468 There are two different ways to use this method. The first is to
469 pass in a day of week and possibly a time:
470
471 $err = $date->prev($dow, $curr [,$time]);
472
473 If $curr = 0, this means to look for the previous occurrence of the
474 day of week, and set the time to the value passed in (or current
475 time if no time was passed in). The day is ALWAY less than the
476 current day. If the current day is the same day of week as $dow,
477 then the date returned will be one week earlier.
478
479 If $curr = 1, it means to look for the current or previous
480 occurrence of the day of week, and set the time to the value passed
481 in (or 00:00:00 if none was passed in). If the current day of week
482 is the same as $dow, the date will remain unchanged. Since the time
483 is then set, the new date may actually occur after the original
484 date depending on the value of $time.
485
486 If $curr = 2, it means to look for the last time (not counting now)
487 that the day of week at the given time occurred. The date may be
488 the same as the original date.
489
490 $time may be a list reference of [H,MN,S], [H,MN], or [H].
491
492 The following examples should illustrate the use of this function.
493
494 Original Date = Fri Nov 22 18:15:00
495
496 dow curr time new date
497
498 4 (Thu) 0/1/2 undef Thu Nov 21 00:00:00
499 4 0/1/2 [12,30,0] Thu Nov 21 12:30:00
500
501 5 (Fri) 0/2 undef Fri Nov 15 18:15:00
502 5 1 undef Fri Nov 22 18:15:00
503
504 5 0 [12,30,0] Fri Nov 15 12:30:00
505 5 1/2 [12,30,0] Fri Nov 22 12:30:00
506
507 5 0/2 [19,30,0] Fri Nov 15 19:30:00
508 5 1 [19,30,0] Fri Nov 22 19:30:00
509
510 The second way to use this method is by passing in undef for the
511 day of week.
512
513 $err = $date->prev(undef,$curr,$time);
514
515 In this case, a time is required and it must be a list reference of
516 3 elements: [H, MN, S]. Any or all of the elements may be undef.
517
518 The new date is the previous occurrence of the time.
519
520 If you define hours, then minutes and seconds may be defined, or
521 default to 0 and you are looking for a previous time that the
522 specified time (HH:00:00) occurred (which might be as much as 24
523 hours in the past).
524
525 If hours are undefined and minutes are defined, then seconds may be
526 defined, or default to 0, and you are looking for the last time the
527 minutes/seconds (MN:SS) appeared on the digital clock, which will
528 be sometime in the past hour.
529
530 Finally, if hours and minutes are undefined, seconds must be
531 defined (or default to zero) and the last time that that second
532 occurred will be returned (which will be sometime in the past
533 minute).
534
535 If $curr is non-zero, the current time is returned if it matches
536 the criteria passed in, so the returned value will be now or in the
537 past. If $curr is zero, the time returned will definitely be in
538 the past.
539
540 DATE = Fri Nov 22 18:15:00
541
542 curr hr min sec returns
543 0/1 18 undef undef Nov 22 18:00:00
544 0/1 18 30 0 Nov 21 18:30:00
545 0 18 15 undef Nov 21 18:15:00
546 1 18 15 undef Nov 22 18:15:00
547 0 undef 15 undef Nov 22 17:15:00
548 1 undef 15 undef Nov 22 18:15:00
549
550 printf
551 $out = $date->printf($in);
552 @out = $date->printf(@in);
553
554 This takes a string or list of strings which may contain any number
555 of special formatting directives. These directives are replaced
556 with information contained in the date. Everything else in the
557 string is returned unmodified.
558
559 A directive always begins with '%'. They are described in the
560 section below in the section PRINTF DIRECTIVES.
561
562 secs_since_1970_GMT
563 $secs = $date->secs_since_1970_GMT();
564
565 This returns the number of seconds that have elapsed since Jan 1,
566 1970 00:00:00 GMT (negative if the date is earlier).
567
568 The reverse is also allowed:
569
570 $err = $date->secs_since_1970_GMT($secs);
571
572 which sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT
573 in the local time zone.
574
575 set
576 $err = $date->set($field,@vals [,$isdst]);
577
578 This explicitly sets one or more fields in a date.
579
580 $field can be any of the following:
581
582 $field @vals
583
584 zone [ZONE] ZONE can be any zone or alias
585
586 zdate [ZONE,]DATE sets the zone and entire date
587
588 date DATE sets the entire date
589
590 time TIME sets the entire time
591
592 y YEAR sets one field
593 m MONTH
594 d DAY
595 h HOUR
596 mn MINUTE
597 s SECOND
598
599 Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME
600 is a list reference containing [H,MN,S].
601
602 ZONE is optional (it defaults to the local zone as defined either
603 by the system clock, or the SetDate or ForceDate config variables).
604 If it is passed in, it can be any zone name, abbreviation, or
605 offset. An offset can be expressed either as a valid offset string,
606 or as a list reference. Refer to the join/split functions of
607 Date::Manip::Base for information on valid offset strings.
608
609 An optional last argument is $isdst (which must be 0 or 1) is
610 included when setting a date which could be in either standard time
611 or daylight saving time. It is ignored in all other situations. If
612 it is not included, and the resulting date could be in either, it
613 will default to standard time.
614
615 The $date object must contain a valid date (unless the entire date
616 is being set with $field set to either "zdate" or "date").
617
618 If $field is "zone", the time zone of the date will be set. If ZONE
619 is not passed in, it will be set to the local time zone. When
620 setting the time zone, no conversion is done! Whatever date and
621 time is stored in the $date object prior to this remains
622 unchanged... except it will be that date and time in the new time
623 zone.
624
625 If $field is "zdate", the entire date and time zone is set. If ZONE
626 is not passed in, it is set to the local time zone.
627
628 If $field is "date", the entire date will be set, but the time zone
629 of the date will not be changed.
630
631 If $field is "time", or one of the individual fields, only those
632 fields will be modified.
633
634 An error is returned if an invalid argument list is passed in, or
635 if the resulting date is checked and found to be invalid.
636
637 value
638 $val = $date->value([$type]);
639 @val = $date->value([$type]);
640
641 These return the value of the date stored in the object.
642
643 In scalar context, a printable string in the form YYYYMMDDHH:MN:SS
644 is returned. In list context, a list is returned of (Y,M,D,H,MN,S).
645
646 If $type is omitted, the date is returned in the time zone it was
647 parsed in.
648
649 If $type is "local", it is returned in the local time zone (which
650 is either the system time zone, or the zone specified with the
651 SetDate or ForceDate config variables).
652
653 If $type is "gmt", the date is returned in the GMT time zone.
654
655 An empty string or list is returned in the case of an error (and an
656 error code is set).
657
658 week_of_year
659 $wkno = $date->week_of_year([$first]);
660
661 This figures out the week number. If $first is passed in, it must
662 be between 1 and 7 and refers to the first day of the week. If
663 $first is not passed in, the FirstDay config variable is used.
664
665 NOTE: This routine should only be called in rare cases. Use printf
666 with the %W, %U, %J, %L formats instead. This routine returns a
667 week between 0 and 53 which must then be "fixed" to get into the
668 ISO 8601 weeks from 1 to 53. A date which returns a week of 0
669 actually belongs to the last week of the previous year. A date
670 which returns a week of 53 may belong to the first week of the next
671 year.
672
674 The following issues may occur when parsing dates that should be
675 understood to make full use of this module.
676
677 Complete vs. truncated dates and times
678 Date formats are either complete or truncated. A complete date
679 fully specifies the year, month, and day and a complete time fully
680 specifies the hour, minute, and second.
681
682 It should be understood that in many instances, the information may
683 be implied rather than explicitly stated, but it is still treated
684 as complete.
685
686 For example, the date "January 3" is complete because it implies
687 the current year.
688
689 A truncated calendar date or time does not include information
690 about some of the fields. Date::Manip will never work with a
691 partial date or time, so defaults will be supplied.
692
693 For example, the date "2009-01" is missing a day field, so a
694 default will be used. In this case, the day will be the 1st, so
695 this is equivalent to "Jan 1st 2009". If only the year is given, it
696 will default to Jan 1.
697
698 If the time, or any of it's components is missing, they default to
699 00. So the time "12:30" and "12:30:00" are equivalent.
700
701 The "complete" method can be used to check what type of date was
702 parsed, and which values were specified (either explicitly or
703 implied) and which were provided as a default. It should be noted
704 that there is no way to differentiate between an explicit and
705 implied value.
706
707 A string with a date and/or time may consist of any of the
708 following:
709
710 a complete date and a time (complete or truncated)
711 a truncated date with no time
712 a time (complete or truncated) with no date
713
714 In other words, the date "Jan 2009 12:30" is not valid since it
715 consists of a time with a truncated date.
716
718 When specifying a time zone, it can be done in three different ways.
719 One way is to specify the actual time zone. The second is to supply a
720 valid time zone abbreviation. The third is to specify an offset (with
721 an optional abbreviation). The following dates illustrate the these
722 formats.
723
724 The timezone information always follows the time immediately, and may
725 only be included if a time is included. The following examples use an
726 ISO 8601 format for the date/time, but any of the other date and time
727 formats may be used.
728
729 The first way to specify the time zone is to specify it by complete
730 name (or using one of the standard aliases):
731
732 2001-07-01-00:00:00 America/New_York
733
734 Although this is unambiguous when it comes to determining the time
735 zone, the time is ambiguous in most zones for one hour of the year.
736 When a time change occurs during which the clock is moved back, the
737 same wall clock time occurs twice.
738
739 For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in
740 the morning, the clock was set back to 01:00. As a result, the date Nov
741 2, 2008 at 01:30 is ambiguous. It is impossible to determine if this
742 refers to the 01:30 that occurred half an hour before the time change,
743 or the one 30 minute after the change.
744
745 In practice, if this form is used, the date will be assigned to
746 standard time, meaning that there will be some times (typically 1 hour
747 per year) which cannot be expressed this way. As such, this method is
748 discouraged.
749
750 The second way to specify the time zone, which is the most common, is
751 to use a time zone abbreviation:
752
753 2001-07-01-00:00:00 EDT
754
755 Unfortunately, the abbreviation does not uniquely determine the time
756 zone except in a few cases. In order to assign a time zone, Date::Manip
757 will refer to a list of all time zones which use the abbreviation.
758 They will be tested, in the order given in the Date::Manip::Zones
759 documentation, and the first match (i.e. the one in which the given
760 date/time and abbreviation are valid) determines the time zone which
761 will be used. A great deal of effort has been made to ensure that the
762 most likely time zone will be obtained (i.e. the most common time zones
763 are tested before less common ones), so in most cases, the desired
764 results will be obtained.
765
766 If the default order does not yield the desired time zone, the order of
767 testing can be modified using the abbrev method described in the
768 Date::Manip::TZ documentation.
769
770 Although the time zone is ambiguous, the date is not, since only time
771 zones for which the date are valid will be used.
772
773 The third way to specify the time zone is by specifying an offset and
774 an optional abbreviation:
775
776 2001-07-01-00:00:00 -04
777 2001-07-01-00:00:00 -0400
778 2001-07-01-00:00:00 -040000
779 2001-07-01-00:00:00 -04:00
780 2001-07-01-00:00:00 -04:00:00
781
782 2001-07-01-00:00:00 -04 (EDT)
783 2001-07-01-00:00:00 -0400 (EDT)
784 2001-07-01-00:00:00 -040000 (EDT)
785 2001-07-01-00:00:00 -04:00 (EDT)
786 2001-07-01-00:00:00 -04:00:00 (EDT)
787
788 2001-07-01-00:00:00 -04 EDT
789 2001-07-01-00:00:00 -0400 EDT
790 2001-07-01-00:00:00 -040000 EDT
791 2001-07-01-00:00:00 -04:00 EDT
792 2001-07-01-00:00:00 -04:00:00 EDT
793
794 The offset almost never sufficient to uniquely determine the time zone
795 (and it is not even guaranteed that both the offset and abbreviation
796 will, though in practice, it is probably sufficient). In this instance,
797 the time zone will be determined by testing all time zones which have
798 the given offset (and abbreviation if it is included) until one is
799 found which matches both pieces of information. For more information
800 about how this testing is done, refer to the def_zone method of the
801 Date::Manip::TZ documentation.
802
804 There are several categories of date formats supported by Date::Manip.
805 These are strings which specify only the year/month/day fields.
806
807 These formats explicitly set the date, but not the time. These formats
808 may be combined with a time string (as specified below) to set both the
809 date and time. If this is not done, the default time is determined by
810 the DefaultTime config variable.
811
812 ISO 8601 dates
813 The preferred date formats are those specified by ISO 8601. The
814 specification includes valid calendar date and valid time formats.
815 Date::Manip will handle all of these formats, but does not require
816 that the dates rigidly adhere to the specification since the
817 ultimate goal of Date::Manip is to handle dates as they are
818 represented in real life and some common variations exist which are
819 similar to, but not identical to, those from the specification.
820
821 A calendar date includes the following fields:
822
823 CC 2-digit representation of the century
824 YY 2-digit representation of the year in
825 a century
826 MM 2-digit representation of a month
827 DD 2-digit representation of a day of month
828 DoY 3-digit representation of a day of year
829 (001-366)
830 Www the character "W" followed by a 2-digit
831 week of the year (01-53)
832 D the day of the week (1-7)
833
834 The following date formats are considered complete by Date::Manip.
835 In the following, the date Thu Mar 5 2009 is used as an example.
836 This is the 64th day of the year. Thu is the 4th day of the week.
837 The week starting Mon, Mar 2 is the 10th week of the year
838 (according the the ISO 8601 definition). Obviously, some of the
839 formats are only valid when used at some times. For example, the
840 format --MMDD refers to a month and day in the current year, so the
841 date Mar 5, 2009 can only be specified using this format during
842 2009.
843
844 Format Notes Examples
845
846 CCYYMMDD 20090305
847 CCYY-MM-DD 2009-03-05
848
849 YYMMDD 1,2,4 090305
850 YY-MM-DD 09-03-05
851
852 -YYMMDD 3,4 -090305
853 -YY-MM-DD -09-03-05
854
855 --MMDD 1 --0305
856 --MM-DD --03-05
857
858 ---DD 1 ---05
859
860
861 CCYYDoY 2009064
862 CCYY-DoY 2009-064
863
864 YYDoY 1,4 09064
865 YY-DoY 09-064
866
867 -YYDoY 3,4 -09064
868 -YY-DoY -09-064
869
870 -DoY 1 -064
871
872
873 CCYYWwwD 2009W104
874 CCYY-Www-D 2009-W10-4
875
876 YYWwwD 1,4 09W104
877 YY-Www-D 09-W10-4
878
879 -YYWwwD 3,4 -09W104
880 -YY-Www-D -09-W10-4
881
882 -YWwwD 1 -9W104
883 -Y-Www-D -9-W10-4
884 Y is the year (0-9) in
885 current decade
886
887 -WwwD 1 -W104
888 -Www-D -W10-4
889
890 -W-D 1 -W-4
891 D is day (1-7) in
892 current week
893
894 ---D 1 ---4
895 same as -W-D
896
897 The following date formats are truncated:
898
899 CCYY-MM 2 2009-03 (2009-03-01)
900
901 CCYY 2009 (2009-01-01)
902
903 CC 2 20 (2000-01-01)
904
905 -YYMM 4 -0903
906 -YY-MM -09-03
907
908 -YY 4 -09
909
910 --MM --03
911
912 CCYYWww 2009W10
913 CCYY-Www 2009-W10
914
915 YYWww 4 09W10
916 YY-Www 09-W10
917
918 -YYWww 3,4 -09W10
919 -YY-Www -09-W10
920
921 -Www -W10
922
923 Notes:
924
925 1 These formats are considered truncated in the standard, but
926 since
927 they do include (or imply, using the current date for defaults)
928 all of the fields, and since they do not introduce any parsing
929 complexities, the standard is relaxed, and they are treated as
930 complete.
931
932 2 These formats are treated differently than in Date::Manip 5.xx
933 as
934 described below.
935
936 3 These formats are not defined in the ISO 8601 spec, but
937 are added for the sake of completeness since they do not
938 add any parsing incompatibilities.
939
940 4 Formats where the century is not given are described as a year
941 in
942 the current century in the specification. Date::Manip treats
943 this
944 more generically using the YYtoYYYY config variable. This will
945 be
946 used to determine how to determine the full year.
947
948 Date::Manip 5.xx handled ISO 8601 dates in a less rigid fashion,
949 and deviated from the specification in several formats. As of 6.00,
950 the specification is followed much more closely so that all of the
951 date formats included in it should produce valid dates. This
952 changes, in a backwards incompatible way, the way a few strings
953 will be interpreted as dates.
954
955 As of 6.00, a two-digit date will be treated as CC. Previously, it
956 was treated as YY.
957
958 A six-digit date will be treated as YYMMDD. Previously, it was
959 treated as YYYYMM.
960
961 Previously, dashes were treated as optional in many cases.
962 According to the specification, dates may be written in expanded
963 form (with all dashes present) or abbreviate form (with no dashes).
964 As of 6.00, this is the behavior, so the formats: YYMMDD and YY-MM-
965 DD are allowed, as per the specification, but the format YY-MMDD is
966 NOT allowed (though it was previously).
967
968 The Www-D formats require a bit of explanation. According to the
969 specification, the date:
970
971 1996-w02-3
972
973 refers to the day with an ordinal number of 3 within the calendar
974 week in the 2nd week of 1996.
975
976 In the specification, the days of the week are numbered from 1 to 7
977 (Monday to Sunday), and the week always begins on Monday, so day 1
978 (Monday) is always the first day of the week, day 2 (Tuesday) is
979 always the second day of the week, etc.
980
981 In Date::Manip, the constraint that the week must start with Monday
982 is relaxed, allowing the week to begin with Sunday (a far more
983 common start of the week in calendars, at least in some parts of
984 the world).
985
986 This presents a problem though in that the above date could be
987 interpreted as Wednesday (day 3) of the 2nd week of 1996, or as the
988 3rd day of the 2nd week of 1996 (which would normally be Wednesday,
989 but would be Tuesday if the week begins on Sunday).
990
991 As of Date::Manip 6.00, the above date will be interpreted as the
992 3rd day of the 2nd week. This is a reversal from Date::Manip 5.xx,
993 but I believe is what the specification would require. For more
994 information, refer to the Date::Manip::Changes document.
995
996 Common date formats
997 Date::Manip supports a number of common date formats. The following
998 fields may be included in a date:
999
1000 YY 2-digit representation of the year
1001 YYYY 4-digit representation of the year
1002 M 1- or 2- digit representation of the month
1003 MM 2-digit representation of the month
1004 D 1- or 2- digit representation of the day
1005 DD 2-digit representation of the day
1006 mmm The abbreviated or full month name (i.e. Jan)
1007
1008 The following date formats are supported:
1009
1010 Format Notes Examples
1011
1012 M/D 1,2,3 3/5
1013 M/D/YY 1 3/5/09
1014 M/D/YYYY 1 3/5/2009
1015
1016 YYYY/M/D 2009/3/5
1017
1018 mmm/D Mar/5
1019 mmm/D/YY Mar/5/09
1020 mmm/D/YYYY Mar/5/2009
1021 D/mmm 5/Mar
1022 D/mmm/YY 5/Mar/09
1023 D/mmm/YYYY 5/Mar/2009
1024 YYYY/mmm/D 2009/Mar/5
1025
1026 mmmD Mar5
1027 mmmDDYY 4 Mar0509
1028 mmmDDYYYY Mar052009
1029 Dmmm 5Mar
1030 DmmmYY 5Mar09
1031 DmmmYYYY 5Mar2009
1032 YYYYmmmD 2009Mar5
1033
1034 mmmD YY Mar5 09
1035 mmmD YYYY Mar5 2009
1036 Dmmm YY 5Mar 09
1037 Dmmm YYYY 5Mar 2009
1038
1039 mmm/D YY Mar/5 09
1040 mmm/D YYYY Mar/5 2009
1041 D/mmm YY 5/Mar 09
1042 D/mmm YYYY 5/Mar 2009
1043
1044 YY mmmD 09 Mar5
1045 YYYY mmmD 2009 Mar5
1046 YY Dmmm 09 5Mar
1047 YYYY Dmmm 2009 5Mar
1048
1049 YY mmm/D 09 Mar/5
1050 YYYY mmm/D 2009 Mar/5
1051 YY D/mmm 09 5/Mar
1052 YYYY D/mmm 2009 5/Mar
1053
1054 YYYY:MM:DD 2010:01:15 (EXIF format)
1055
1056 mmmYYYY 4 Jun 2010
1057 YYYYmmm 4 2010 June
1058 mmm/YYYY 4 Jun/2010
1059 YYYY/mmm 4 2010/Jun
1060
1061 In the formats above, the slash (/) can be replace by any of the
1062 valid separators: whitespace, slash (/), period (.), or dash (-).
1063 The dash, though allowed, is discouraged since it may conflict with
1064 an ISO 8601 format. For example, the format MM/DD/YY is just fine,
1065 but MM-DD-YY does not work since it conflicts with YY-MM-DD. To be
1066 safe, if "-" is used as a separator in a non-ISO format, they
1067 should be turned into "/" before calling the Date::Manip routines
1068 or you should use the 'noiso8601' option with the parse or
1069 parse_date methods.
1070
1071 No matter what separator is used, the same separator must be used
1072 throughout the date. For example, MM/DD/YY is valid and MM.DD.YY is
1073 also valid, but MM/DD.YY is NOT valid.
1074
1075 Notes:
1076
1077 1 With these formats, Americans tend to write month first, but
1078 many
1079 other countries tend to write day first. The latter behavior
1080 can be
1081 obtained by setting the config variable DateFormat to something
1082 other
1083 than "US".
1084
1085 2 The dot (.) separator may not be used in the M/D format since it
1086 will be interpreted as the H12,H+ format described below.
1087
1088 3 The M/D format should not use the period (.) separator as that
1089 will
1090 incorrectly match the HH,H+ time format.
1091
1092 4 Historically, I have not supported partial dates (i.e. dates
1093 that
1094 were not fully specified), but it has been argued that something
1095 like
1096 'Jun 1910' would be interpreted by almost everyone as a day in
1097 June
1098 of 1910 instead of June 19, 2010. And it has been shown that in
1099 some applications, dates are specified in that way. I have
1100 added the
1101 new config variable Format_MMMYYYY which will change this. If
1102 this
1103 variable is not set, the formats allowed are:
1104
1105 mmmDDYY
1106
1107 If it is set, the formats allowed are:
1108
1109 mmmYYYY
1110 YYYYmmm
1111
1112 The day of week may not be included with these formats. When
1113 parsing a full date/time, if Format_MMMYYYY is set to 'first',
1114 it returns the 1st of the month at midnight. If it is set to
1115 'last', it returns the last day at 23:59:59. If parsing only
1116 only a date, it will be set to the first or last day of the
1117 month at midnight.
1118
1119 These formats explicitly set the date, but not the time. The
1120 default time is determined by the DefaultTime config variable.
1121
1122 Less common date formats
1123 The following formats are also supported by Date::Manip:
1124
1125 DoW
1126 The day of week of the current week
1127 Friday
1128 Friday at 12:40
1129
1130 MMM Nth [YYYY]
1131 Nth MMM [YYYY]
1132 YYYY MMM Nth
1133 YYYY Nth MMM
1134 Dec 1st 1970
1135 1st Dec 1970
1136 1970 Dec 1st
1137 1970 1st Dec
1138
1139 next/prev DoW
1140 The next or last occurrence of DoW
1141 next Friday
1142 last Friday at 12:40
1143
1144 next/last week/month/year
1145 The day one week/month/year from now
1146 or in the past
1147 next week
1148 last month at 15:00
1149
1150 last day in MMM [YYYY]
1151 The last day of the month
1152 last day in October
1153 last day in October 1996
1154
1155 last DoW in MMM [YYYY]
1156 The last DoW in the month
1157 last Tuesday in October
1158 last Tuesday in October 1996
1159
1160 last DoW in YYYY
1161 The last DoW in the year
1162 last Tuesday in 1997
1163
1164 NOTE: "last DoW" doesn't work in
1165 English since the word "last"
1166 is used for both this expression
1167 and for "prev DoW", which gets
1168 parsed first. "last DoW" MAY
1169 work in other languages.
1170
1171 Nth DoW in MMM [YYYY]
1172 The Nth DoW in the month
1173 3rd Tuesday in October
1174 3rd Tuesday in October 1996
1175
1176 Nth DoW [YYYY]
1177 The Nth DoW in the year
1178 22nd Sunday
1179 22nd Sunday in 1996
1180
1181 Nth day in MMM [YYYY]
1182 The Nth day of the month
1183 1st day of February
1184 1st day of February 2012
1185
1186 DoW week
1187 British: same as "in 1 week on DoW"
1188 Monday week
1189
1190 DoW week N [YYYY]
1191 Dow Nth week [YYYY]
1192 Sunday week 22
1193 Sunday 22nd week
1194 These refer to the day of week
1195 of the Nth week of the year.
1196
1197 Nth
1198 12th
1199 This refers to the Nth day of the
1200 current month.
1201
1202 Note that the formats "Sunday week 22" and "22nd Sunday" give
1203 different behaviors. "Sunday week 22" returns the Sunday of the
1204 22nd week of the year based on how week 1 is defined. ISO 8601
1205 defines week one to contain Jan 4, so "Sunday week 1" might be the
1206 first or second Sunday of the current year, or the last Sunday of
1207 the previous year. "22nd Sunday" gives the actual 22nd time Sunday
1208 occurs in a given year, regardless of the definition of a week.
1209
1210 Special date strings
1211 Most languages have strings which can be used to specify the date
1212 (relative to today). In English, these include the strings:
1213
1214 today
1215 tomorrow
1216 yesterday
1217
1218 There is also support for the British formats:
1219
1220 today week
1221 tomorrow week
1222 yesterday week
1223
1224 which refer to one week after today/tomorrow/yesterday
1225 respectively.
1226
1227 Other languages have similar strings.
1228
1229 Holidays
1230 You can parse holiday names as dates (including timezones). For
1231 example:
1232
1233 Christmas
1234 Christmas 2010
1235 Christmas 2010 at noon
1236 Christmas 2010 at noon PST
1237 Saturday Christmas 2010 at noon
1238
1239 In all of the formats (except for ISO 8601 formats), the day of week
1240 ("Friday") can be entered anywhere in the date and it will be checked
1241 for accuracy. In other words,
1242
1243 "Tue Jul 16 1996 13:17:00"
1244
1245 will work but
1246
1247 "Jul 16 1996 Wednesday 13:17:00"
1248
1249 will not (because Jul 16, 1996 is Tuesday, not Wednesday).
1250
1252 Although Date::Manip has some support for parsing dates in foreign
1253 languages, it must be noted that the formats supported are largely
1254 based on English equivalents.
1255
1256 There are probably many different dates that are perfectly valid, and
1257 in common usage, in other languages which do not have an equivalent in
1258 the English language, and unfortunately, Date::Manip will probably not
1259 parse these.
1260
1261 You are free to send these to me, and I'll see if there is a way to add
1262 them in, but I do not guarantee anything. Without having a full-blown
1263 language parser (or at least the portion of the language that is
1264 devoted to calendar and time), most of these formats will simply not be
1265 supportable.
1266
1268 There are several categories of time formats supported by Date::Manip.
1269 These are strings which specify only the hour/minute/second fields.
1270
1271 ISO 8601 times
1272 A time may be also be complete or truncated. Again, Date::Manip
1273 treats some formats as complete even though the specification calls
1274 them truncated.
1275
1276 A time may include the following fields:
1277
1278 HH 2-digit representation of the hour
1279 MN 2-digit representation of the minutes
1280 SS 2-digit representation of the seconds
1281 H+ 1+ digit representation of fractional hours
1282 M+ 1+ digit representation of fractional minutes
1283 S+ 1+ digit representation of fractional seconds
1284
1285 The following time formats are considered complete by Date::Manip.
1286 The time 12:30:15 will be expressed in the examples.
1287
1288 Format Notes Examples
1289
1290 HHMNSS 2 123015
1291
1292 HH:MN:SS 12:30:15
1293
1294 HHMNSS,S+ 123015,5
1295 HH:MN:SS,S+ 12:30:15,5
1296 Fractional seconds are ignored
1297
1298 HHMN,M+ 1230,25
1299 HH:MN,M+ 12:30,25
1300 This is 12:30:00 + 0.25 minutes
1301
1302 HH,H+ 12,5
1303 This is 12:00:00 + 0.5 hours, so
1304 this is equivalent to 12:30:00
1305
1306 -MNSS 1 -3015
1307 -MN:SS -30:15
1308
1309 --SS 1 --15
1310
1311 -MNSS,S+ 1 -3015,5
1312 -MN:SS,S+ -30:15,5
1313
1314 -MN,M+ 1 -30,25
1315
1316 --SS,S+ 1 --15,5
1317
1318 HHMN 3 1230
1319 HH:MN 12:30
1320
1321 The following time formats are truncated:
1322
1323 HH 12
1324
1325 -MN -30
1326
1327 Notes:
1328
1329 1 These formats are considered truncated in the standard, but
1330 since
1331 they do include (or imply, using the current time for defaults)
1332 all of
1333 the fields, and since they do not introduce any parsing
1334 complexities,
1335 the standard is relaxed, and they are treated as complete.
1336
1337 2 The HHMNSS format will not be correctly parsed since it is
1338 impossible
1339 to distinguish between it and YYMMDD. In order to parse an all-
1340 digit
1341 time, add the string ",0" to the end to force it to be
1342 interpreted
1343 as a time or include time zone information (either a zone name
1344 or
1345 abbreviation... an offset will not work in this case).
1346
1347 3 The HH:MN format will be treated as complete, even though it is
1348 incomplete due to missing the seconds. In real life, expressing
1349 a time in the HH:MN format is very common, and is regarded as
1350 complete,
1351 and might include time zone information.
1352
1353 ISO 8601 times may be followed by a time zone unless they are
1354 truncated. Truncated times may not include a timezone.
1355 Date::Manip relaxes the constraints placed on the time zone format
1356 and allows any of the methods used to specify the time zone
1357 including time zone name, abbreviation, or offset. The time zone
1358 may be separated from the time by a space, but it is not required.
1359
1360 Another constraint that is relaxed is that the fractional part may
1361 be specified using a period. In other words, the following are
1362 equivalent:
1363
1364 12:30,25
1365 12:30.25
1366
1367 It should be noted (as it is in the specification) that using a
1368 negative time zone offset may cause confusion. In addition to
1369 visually confusing, it may not be parsed correctly. For example,
1370 the time:
1371
1372 123005-0300
1373
1374 may not be parsed correctly. When using an offset time zone, you
1375 should always use the colon separators in the time:
1376
1377 12:30:05-0300
1378
1379 Other time formats
1380 A time may include any of the following fields:
1381
1382 H24 1- or 2-digit representation of the hour (0-23)
1383 H12 1- or 2-digit representation of the hour (1-12)
1384 MN 2-digit representation of the minutes
1385 SS 2-digit representation of the seconds
1386 H+ 1+ digit representation of fractional hours
1387 M+ 1+ digit representation of fractional minutes
1388 S+ 1+ digit representation of fractional seconds
1389 AM A language specific AM/PM string
1390
1391 The following time formats are accepted:
1392
1393 Format Examples
1394
1395 H24:MN:SS 17:30:15
1396 H12:MN:SS AM 5:30:15 PM
1397 H12:MN:SS
1398
1399 H24:MN:SS,S+ 17:30:15,5
1400 H12:MN:SS,S+ AM 5:30:15,5 PM
1401 H12:MN:SS,S+ Fractional seconds are ignored
1402
1403 H24:MN,M+ 17:30,25
1404 H12:MN,M+ AM 5:30,25 PM
1405 H12:MN,M+ This is 17:30:00 + 0.25 minutes
1406
1407 H24,H+ 17,5
1408 H12,H+ AM 5,5 PM
1409 H12,H+ This is 17:00:00 + 0.5 hours, so
1410 this is equivalent to 17:30:00
1411
1412 H24:MN 17:30
1413 H12:MN AM 5:30 PM
1414 H12:MN
1415
1416 H12 AM 5 PM
1417
1418 The fractional part may be specified using a comma or a period.
1419 Fractional seconds may also be separated using a colon. A language
1420 specific fractional separator may also be available for some
1421 languages.
1422
1423 In other words, the following are equivalent:
1424
1425 12:30:20,25
1426 12:30:20.25
1427 12:30:20:25
1428
1429 Some languages have alternate H:MN and MN:S separators. For
1430 example, one H:MN separator in French is 'h' (the MN:S separator is
1431 still a colon), so the following are equivalent:
1432
1433 12:30:00
1434 12h30:00
1435
1436 Time zone information can be included immediately following the
1437 time. It can be separated by whitespace from the time, or it can
1438 be immediately adjacent.
1439
1440 Special time strings
1441 Different languages may have some words which can be used to
1442 specify a certain time of day. In English, for example, the
1443 following words are equivalent to the time listed:
1444
1445 noon 12:00:00
1446 midnight 00:00:00
1447
1448 So, the following are equivalent:
1449
1450 Jan 2 2009 at noon
1451 Jan 2 2009 12:00:00
1452
1453 There were two possible ways to interpret midnight. One was at the
1454 start of the day (00:00:00) and the other was at the end of the day
1455 (24:00:00 which would actually mean at 00:00:00 of the following
1456 day). The first has been used to maintain backwards compatibility
1457 with Date::Manip 5.xx .
1458
1459 Other languages have similar strings.
1460
1461 In most languages, a word similar to "at" may precede the time (this
1462 does NOT apply to ISO 8601 time formats). This word (which must be
1463 separate from all other parts of the date with whitespace) is optional,
1464 and the following are equivalent:
1465
1466 12:30
1467 at 12:30
1468
1469 The times "12:00 am", "12:00 pm", and "midnight" are not well defined.
1470 Date::Manip uses the following convention:
1471
1472 midnight = 12:00am = 00:00:00
1473 noon = 12:00pm = 12:00:00
1474
1475 and the day goes from 00:00:00 to 23:59:59. In other words, midnight
1476 is the beginning of a day rather than the end of one. The time
1477 24:00:00 is also allowed (though it is automatically transformed to
1478 00:00:00 of the following day). This gives the unusual result of
1479 parsing:
1480
1481 Wed Feb 8 2006 24:00:00
1482
1483 which gives the date of:
1484
1485 Thu Feb 9 2006 00:00:00
1486
1488 There are several categories of strings which specify both the date and
1489 time. These include the following:
1490
1491 ISO 8601 combined date and time
1492 A combined ISO 8601 date and time is a string containing a complete
1493 ISO 8601 date and a complete or truncated ISO 8601 time. It may
1494 also include a timezone, provided a complete time is included.
1495
1496 Date::Manip relaxes the restrictions on how the two are combined.
1497 The time may be separated from the date by space, dash, or the
1498 letter T, or the two may be joined with nothing separating them.
1499
1500 When the time immediately follows the date, or when the two are
1501 separated by a dash, the resulting string MUST be unambiguous.
1502 Provided the date includes all of the dashes in it (i.e. YY-MM-DD
1503 instead of YYMMDD), it is rare that there is any ambiguity. If the
1504 date does not include dashes, the strings may be ambiguous, and in
1505 this case, separating the date and time with a space or the letter
1506 T is useful (and perhaps necessary) to correctly interpret the
1507 string.
1508
1509 The DoY formats should always be separated from the time by
1510 something. They are visually confusing if they are not separated
1511 from the time.
1512
1513 Time zone information can be included immediately following a
1514 complete time. It may not be included if no time is given, or if a
1515 truncated time is included. The time zone may be separated from the
1516 time with whitespace, or it can be immediately adjacent to it
1517 (since the ISO 8601 specification allows it in some cases).
1518
1519 Non-ISO 8601 combined date and time
1520 A date from any of the non-ISO 8601 formats above may be combined
1521 with any of the non-ISO 8601 time formats above in any combination
1522 to form a valid combined date and time.
1523
1524 Deltas
1525 Dates are often specified in terms of a delta from "now". For
1526 example, "in 2 days".
1527
1528 Most valid deltas can be used to specify a date, and the date is
1529 defined as that delta added to "now". Refer to the
1530 Date::Manip::Delta documentation for a list of valid delta formats.
1531
1532 If the delta itself does not include a time part, the time may be
1533 specified explicitly. For example:
1534
1535 in 3 days at 12:00:00
1536 in 3 days at 12:00:00 PST
1537
1538 will take the delta part "in 3 days" and add it to the current
1539 time, then set the time to 12:00:00.
1540
1541 It is NOT allowed to include an explicit time if any time segment
1542 was included in the delta. For example, the following is invalid:
1543
1544 in 3 days 2 hours at 12:00:00
1545
1546 One additional format that is supported is to include only week (or
1547 higher) components in the delta and to set the day of week. For
1548 example:
1549
1550 Friday in 2 weeks
1551 in 2 weeks on Friday
1552 Friday 2 weeks ago
1553 2 weeks ago on Friday at 13:45
1554
1555 These first apply the delta (of weeks, months, and years) to the
1556 current time, and then set the day to the given day-of-week in that
1557 week.
1558
1559 Special date and time strings
1560 Most language have strings which can be used to specify the full
1561 date and time (relative to the current date and time). In English,
1562 these include the string:
1563
1564 now
1565
1566 They may also have a timezone attached:
1567
1568 now PST
1569
1570 Additional combined date and time formats
1571 The following formats are also supported:
1572
1573 epoch SECS
1574 The number of seconds since the epoch
1575 (Jan 1, 1970 00:00:00 GMT). SECS may
1576 be negative to give time before the
1577 epoch.
1578
1579 or
1580
1581 epoch SECS TIMEZONE
1582
1583 A couple of notes:
1584
1585 Commas may be included in all date formats arbitrarily (except for ISO
1586 8601 formats where they may only be included when allowed by the
1587 specification).
1588
1589 The time/time zone is removed from the date before the date is parsed,
1590 so the time may appear before or after the date, or between any two
1591 parts of the date.
1592
1593 The time and the zone do not need to be adjacent, so the string:
1594
1595 Jan 21 17:13:27 2010 -0400
1596
1597 will work. If the timezone is separate from the date, it MUST be
1598 separated from any other portion of the date by whitespace.
1599
1600 Certain words such as "on", "in", "at", "of", etc. which commonly
1601 appear in a date or time are ignored (except in ISO 8601 formats).
1602
1604 The following printf directives are replaced with information from the
1605 date.
1606
1607 Year
1608 %y year - 00 to 99
1609 %Y year - 0001 to 9999
1610
1611 Month, Week
1612 %m month of year - 01 to 12
1613 %f month of year - " 1" to "12"
1614 %b,%h month abbreviation - Jan to Dec
1615 %B month name - January to December
1616
1617 Day
1618 %j day of the year - 001 to 366
1619 %d day of month - 01 to 31
1620 %e day of month - " 1" to "31"
1621 %v weekday abbreviation - " S"," M"," T", ...
1622 %a weekday abbreviation - Sun to Sat
1623 %A weekday name - Sunday to Saturday
1624 %w day of week - 1 to 7 (1=Monday)
1625 %E day of month with
1626 suffix - 1st, 2nd, 3rd...
1627
1628 Hour
1629 %H hour - 00 to 23
1630 %k hour - " 0" to "23"
1631 %i hour - " 1" to "12"
1632 %I hour - 01 to 12
1633 %p AM or PM
1634
1635 Minute, Second, Time zone
1636 %M minute - 00 to 59
1637 %S second - 00 to 59
1638 %Z time zone abbreviation - EDT
1639 %z time zone as GMT offset - +0100 (see Note 4)
1640 %N time zone as GMT offset - +01:00:00
1641
1642 Epoch (see NOTE 3 below)
1643 %s seconds from
1644 1/1/1970 GMT - negative if before
1645 %o seconds from 1/1/1970
1646 in the current time
1647 zone
1648
1649 Date, Time
1650 %c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
1651 %C,%u %a %b %e %H:%M:%S %Z %Y - Fri Apr 28 17:25:57 EDT 1995
1652 %g %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT
1653 %D %m/%d/%y - 04/28/95
1654 %x %m/%d/%y or %d/%m/%y - 04/28/95 or 28/04/95
1655 (Depends on DateFormat variable)
1656 %l date in ls(1) format (see NOTE 1 below)
1657 %b %e %H:%M - Apr 28 17:23 (*)
1658 %b %e %Y - Apr 28 1993 (*)
1659 %r %I:%M:%S %p - 05:39:55 PM
1660 %R %H:%M - 17:40
1661 %T,%X %H:%M:%S - 17:40:58
1662 %V %m%d%H%M%y - 0428174095
1663 %Q %Y%m%d - 19961025
1664 %q %Y%m%d%H%M%S - 19961025174058
1665 %P %Y%m%d%H:%M:%S - 1996102517:40:58
1666 %O %Y-%m-%dT%H:%M:%S - 1996-10-25T17:40:58
1667 %F %A, %B %e, %Y - Sunday, January 1, 1996
1668 %K %Y-%j - 1997-045
1669
1670 Special Year/Week formats (see NOTE 2 below)
1671 %G year, Monday as first
1672 day of week - 0001 to 9999
1673 %W week of year, Monday
1674 as first day of week - 01 to 53
1675 %L year, Sunday as first
1676 day of week - 0001 to 9999
1677 %U week of year, Sunday
1678 as first day of week - 01 to 53
1679 %J %G-W%W-%w - 1997-W02-2
1680
1681 Other formats
1682 %n insert a newline character
1683 %t insert a tab character
1684 %% insert a `%' character
1685 %+ insert a `+' character
1686
1687 All other characters are currently unused, but may be used in the
1688 future. They currently insert the character following the %.
1689
1690 The following multi-character formats also exist:
1691
1692 Extended formats
1693 %<A=NUM> These returns the NUMth value of the %A, %a, and %v formats
1694 %<a=NUM> respectively. In English, that would yield:
1695 %<v=NUM> %<A=2> => Tuesday
1696 %<a=2> => Tue
1697 %<v=2> => T
1698 NUM must be in the range 1-7.
1699
1700 %<B=NUM> These return the NUMth value of the %B and %b formats
1701 %<b=NUM> respectively. In English, that would yield:
1702 %<B=2> => February
1703 %<b=2> => Feb
1704 NUM must be in the range 1-12 (or 01-12).
1705
1706 %<p=NUM> These return the NUMth value of the %p format. In
1707 English, that would yield:
1708 %<p=1> => AM
1709 %<p=2> => PM
1710 NUM must be in the range 1-2.
1711
1712 %<E=NUM> These return the NUMth value of the %E format. In
1713 English, that would yield:
1714 %<E=1> => 1st
1715 %<E=53> => 53rd
1716 NUM must be in the range 1-53.
1717
1718 If a lone percent is the final character in a format, it is ignored.
1719
1720 The formats used in this routine were originally based on date.pl
1721 (version 3.2) by Terry McGonigal, as well as a couple taken from
1722 different versions of the Solaris date(1) command. Also, several have
1723 been added which are unique to Date::Manip.
1724
1725 NOTE 1:
1726
1727 The ls format (%l) applies to date within the past OR future 6 months!
1728 Any date that is before the date NOW - 6 months, or that is on or after
1729 the date NOW + 6 months will have the year printed out.
1730
1731 The later time must be on or after so that there is no ambiguity. If it
1732 is now 2000-06-06-12:00:00, then the date 1999-12-06-12:00:00 will be
1733 written as "Dec 6 12:00" but the date 2000-12-06-12:00:00 will be
1734 written as "Dec 6 2000".
1735
1736 NOTE 2:
1737
1738 The %U, %W, %L, %G, and %J formats are used to support the ISO-8601
1739 format: YYYY-wWW-D. In this format, a date is written as a year, the
1740 week of the year, and the day of the week. Technically, the week may
1741 be considered to start on any day of the week, but Sunday and Monday
1742 are the both common choices, so both are supported.
1743
1744 The %W and %G formats return the week-of-year and the year treating
1745 weeks as starting on Monday.
1746
1747 The %U and %L formats return the week-of-year and the year treating
1748 weeks as starting on Sunday.
1749
1750 Most of the time, the %L and %G formats returns the same value as the
1751 %Y format, but there is a problem with days occurring in the first or
1752 last week of the year.
1753
1754 The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D
1755 format is actually 1992-W53-5. In other words, Jan 1 is treated as
1756 being in the last week of the preceding year. Depending on the year,
1757 days in the first week of a year may belong to the previous year, and
1758 days in the final week of a year may belong to the next year. The week
1759 is assigned to the year which has most of the days. For example, if
1760 the week starts on Sunday, then the last week of 2003 is 2003-12-28 to
1761 2004-01-03. This week is assigned to 2003 since 4 of the days in it
1762 are in 2003 and only 3 of them are in 2004. The first week of 2004
1763 starts on 2004-01-04.
1764
1765 The %U and %W formats return a week-of-year number from 01 to 53. %L
1766 and %G return the corresponding year, and to get this type of
1767 information, you should always use the (%W,%G) combination or (%U,%L)
1768 combination. %Y should not be used as it will yield incorrect results.
1769
1770 %J returns the full ISO-8601 format (%G-W%W-%w).
1771
1772 NOTE 3:
1773
1774 The %s and %o formats return negative values if the date is before the
1775 start of the epoch. Other Unix utilities would return an error, or a
1776 zero, so if you are going to use Date::Manip in conjunction with these,
1777 be sure to check for a negative value.
1778
1779 NOTE 4:
1780
1781 The %z format returns the offset in the RFC 822 specified format +0500
1782 . Most offsets are full hour amounts, so this is not a problem, but
1783 some offsets are irregular (+05:17:30). In this case, the string
1784 returned is +051730 which isn't RFC 822 compliant, but since RFC 822
1785 ignores this situation, I had to decide between returning an incorrect
1786 value, or breaking strict compliance, and I chose the second option.
1787
1789 None known.
1790
1792 Please refer to the Date::Manip::Problems documentation for information
1793 on submitting bug reports or questions to the author.
1794
1796 Date::Manip - main module documentation
1797
1799 This script is free software; you can redistribute it and/or modify it
1800 under the same terms as Perl itself.
1801
1803 Sullivan Beck (sbeck@cpan.org)
1804
1805
1806
1807perl v5.26.3 2017-03-01 Date::Manip::Date(3)