1Date::Manip::Date(3) User Contributed Perl Documentation Date::Manip::Date(3)
2
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 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 calc
37 $date2 = $date->calc($delta [,$subtract]);
38 $delta = $date->calc($date2 [,$subtract] [,$mode]);
39 Please refer to the Date::Manip::Calc documentation for details.
41 cmp
43 $val = $date1->cmp($date2);
44 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 A warning is printed if either of the date objects does not include
52 a valid date.
53 complete
55 $flag = $date->complete([$field]);
56 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 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 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 convert
68 $err = $date->convert([$zone]);
69 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 holiday
75 $name = $date->holiday();
76 $name = $date->event();
77 This returns the name of the holiday if $date is a holiday. If
79 $date is not a holiday, undef is returned. If $date is an unnamed
80 holiday, an empty string is returned.
81 input
83 $str = $date->input();
84 This returns the string that was parsed to form the date.
86 is_business_day
88 $flag = $date->is_business_day($checktime);
89 This returns 1 if $date is a business day.
91 $checktime may be passed in. If it is non-zero, the time is checked
93 to see if the date is a business day and falls within work hours.
94 list_holidays
96 @date = $date->list_holidays([$y]);
97 This returns a list of Date::Manip::Date objects containing all
99 dates during a year which are holidays. The times will all be
100 00:00:00.
101 If $y is not passed in, it will list the holidays in the same year
103 as the date stored in $date.
104 list_events
106 @list = $date->list_events( [$format] );
107 @list = $date->list_events(0 [,$format]);
108 @list = $date->list_events($date1 [,$format]);
109 This returns a list of events. Events are defined in the Events
111 section of the config file (discussed in the Date::Manip::Holidays
112 manual).
113 In the first form, a list of all events active at the precise time
115 stored in $date will be returned.
116 If the first argument evaluates to 0, a list of all events active
118 at any time during that day (Y,M,D) are returned.
119 If the first argument is another date object, all events that are
121 active at any time between the two dates (inclusive) are returned.
122 By default, the list returned is of the form:
124 ( [START, END, NAME],
126 [START, END, NAME],
127 ...
128 )
129 where START is a date object when an event starts, END is a date
131 object when it ends, and NAME is the name of the event. Note that
132 START and END are the actual start and end date of the event and
133 may be outside the range of dates being examined (though the event
134 will obviously overlap the range or it wouldn't be included in the
135 list).
136 If $format is included, it can specify an alternate format for the
138 output. Currently, the only supported format is named "dates" and
139 it returns a list in the form:
140 ( [DATE1, NAME1a, NAME1b, ...],
142 [DATE2, NAME2a, NAME2b, ...],
143 ...
144 )
145 This includes a list of all dates during the range when there is a
147 change in what events are active. DATE1 will always be the start of
148 the range being considered, and (NAME1a, NAME1b, ...) are the list
149 of all events that will be active at that time. At DATE2, the list
150 of active events changes with (NAME2a, NAME2b, ...) being active.
151 It is quite possible that a date be included which has no active
153 events, and in that case, the list of names will be empty.
154 nearest_business_day
156 $date->nearest_business_day([$tomorrowfirst]);
157 This looks for the work day nearest to $date. If $date is a work
159 day, it is left unmodified. Otherwise, it will look forward or
160 backwards in time 1 day at a time until a work day is found. If
161 $tomorrowfirst is non-zero (or if it is omitted and the config
162 variable TomorrowFirst is non-zero), we look to the future first.
163 Otherwise, we look in the past first. In other words, in a normal
164 week, if $date is Wednesday, $date is returned. If $date is
165 Saturday, Friday is returned. If $date is Sunday, Monday is
166 returned. If Wednesday is a holiday, Thursday is returned if
167 $tomorrowfirst is non-nil or Tuesday otherwise.
168 next_business_day
170 prev_business_day
171 $date->next_business_day($off [,$checktime]);
172 $date->prev_business_day($off [,$checktime]);
173 The next_business_day method sets the given date to $off (which can
175 be a positive integer or zero) business days in the future. The
176 prev_business_day method sets the date to $off business days in the
177 past.
178 First, $date is tested. If $checktime is nonzero, the date must
180 fall on a business date, and during business hours. If $checktime
181 is zero, the time check is not done, and the date must simply fall
182 on a business date.
183 If the check fails, the date is moved to the start of the next
185 business day (if $checktime is nonzero) or the next business day at
186 the current time (if $checktime is zero). Otherwise, it is left
187 unmodified.
188 Next, if $off is greater than 0, the day $off work days from now is
190 determined.
191 One thing to note for the prev_business_day method is that if $date
193 check fails, the date is set to the next business date, exactly
194 like next_business_day. In other words, if $date is not a business
195 day, the call:
196 $date->prev_business_day(0 [,$checktime]);
198 moves $date forward in time instead of backward which is
200 nonintuitive, but you just have to think of day 0 as being the next
201 business day if $date is not a business day.
202 As a result, the following two calls ALWAYS give the same result:
204 $date->next_business_day(0 [,$checktime]);
206 $date->prev_business_day(0 [,$checktime]);
207 no matter what date is stored in $date.
209 parse
211 $err = $date->parse($string [,@opts]);
212 This parses a string which should include a valid date and stores
214 it in the object. If the string does not include a valid date, an
215 error is returned. Use the err method to see the full error
216 message.
217 A full date may include a calendar date (year, month, day), a time
219 of day (hour, minute, second), and time zone information. All of
220 this can be entered in many different formats.
221 For information on valid date formats, refer to the section VALID
223 DATE FORMATS. For information on valid time zone information, refer
224 to the section VALID TIME ZONE FORMATS.
225 If no time zone information is included in the date, it is treated
227 as being in the local time zone.
228 If time zone information is included, the date will be kept in that
230 time zone, and all operations will be done in that time zone. The
231 convert method can be used to change the time zone to the local
232 time zone, or to another time zone.
233 Some things to note:
235 All strings are case insensitive. "December" and "DEceMBer" are
237 equivalent.
238 When a part of the date is not given, defaults are used. This is
240 described below in the section "Complete vs. truncated dates and
241 times".
242 The year may be entered as 2 or 4 digits. If entered as 2 digits,
244 it will be converted to a 4 digit year. There are several ways to
245 do this based on the value of the YYtoYYYY config variable. Refer
246 to the Date::Manip::Config documentation for more details.
247 Dates are always checked to make sure they are valid.
249 If any other arguments are passed in, they act as options which may
251 improve the speed of parsing. These include:
252 noiso8601 Do not try to parse the
254 date as an ISO 8601 date
255 or time.
256 nodow Do not try to parse a
257 day-of-week (Monday) in
258 the string.
259 nocommon Do not try to parse the
260 date using the formats
261 in the "Common date
262 formats" section.
263 noother Do not try to parse the
264 date using the "Less common
265 date formats" or a time
266 using the "Other time
267 formats".
268 nospecial Do not try to parse the
269 date using the "Special
270 date strings" formats
271 or a time using the
272 "Special time strings"
273 formats, or as a
274 combined date/time using
275 the "Additional combined
276 date and time" formats.
277 nodelta Do not treat deltas as
278 a date relative to now.
279 parse_date
281 $err = $date->parse_date($string [,@opts]);
282 This parses a string which contains a valid date and sets the date
284 part of the object.
285 If the object contained a valid date, the time is kept unchanged.
287 If the object did NOT contain a valid date, a time of 00:00:00 is
288 used.
289 @opts can be any of the strings described in the parse method
291 above.
292 parse_time
294 $err = $date->parse_time($string);
295 This parses a string and sets the time portion of $date to contain
297 it.
298 If the object contained a valid date, the Y/M/D portion is left
300 unchanged. Otherwise, the current date is used.
301 parse_format
303 $err = $date->parse_format($format,$string);
304 This will parse a date contained in $string based on explicit
306 format information contained in $format.
307 If the format is invalid, $err will contain an error message. If
309 the format is valid, but string doesn't match, an error code of 1
310 is returned.
311 $format is a string containing a regular expression with some
313 special directives (based on the printf directives). These
314 directives are turned into regular expression components, and then
315 the entire string is turned into a regular expression which, if
316 $string matches it, will return the date.
317 The directives available are identical to the printf directives.
319 So, if your $format string contains the directive '%Y', it will
320 match a 4-digit year.
321 All of the printf directives are available, but with a few
323 simplifications:
324 %l This directive is NOT available.
326 %b,%h,%B will all match a month name or
328 abbreviation
329 %v,%a,%A will all match a day abbreviation
331 or name
332 %z,%Z,%N will match any time zone string
334 %n currently not allowed (multi-line
336 matching not currently supported)
337 The format string may not over-specify the date. In other words,
339 you may not include both a %y and %Y directive or both a %j and %m
340 directive.
341 A valid format string will specify any of the following sets of
343 data:
344 Required Optional
346 M D H Mn S Y Zone Day-of-week
348 M D H Mn Y Zone Day-of-week
349 M D Y Zone Day-of-week
350 H Mn S Zone
351 H Mn Zone
352 For example, if you had a date stored as:
354 YYYY.MM-DD
356 you could match it using the following:
358 $date->parse_format('%Y\\.%m\\-%d',$string);
360 If you wanted to extract the date from an apache log line:
362 10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] "GET /favicon.ico ...
364 you could use:
366 $date->parse_format('.*?\\[%d/%b/%Y:%T %z\\].*',$line);
368 In your format string, you may use capture buffers that can be back
370 referenced elsewhere in the regular expression. If you use numbered
371 back references, just be aware that all of the directives create a
372 single capture buffer (except for the directives like %% which
373 match a special character instead of a portion of a date). If you
374 use named buffers, do NOT use any of the following as they will
375 conflict with the capture buffers created with the standard
376 directives:
377 y
379 m
380 d
381 h
382 mn
383 s
384 mon_name
385 mon_abb
386 dow_name
387 dow_abb
388 dow_char
389 dow_num
390 doy
391 nth
392 ampm
393 epochs
394 epocho
395 tzstring
396 off
397 abb
398 zone
399 g
400 w
401 l
402 u
403 To be safe, it is suggested that named capture buffers start with a
405 capital letter.
406 There is one other caveat if the %x directive is used. The format
408 is converted to a regular expression and then cached (so that a
409 format can be reused without the penalty of doing the conversion to
410 a regular expression, so if you need to set the DateFormat config
411 variable (which determines the meaning of the %x directive), it
412 must be done before a format string containing %x is used. If the
413 DateFormat config variable is set afterwards, the format string
414 will reflect the old, NOT THE NEW, value of DateFormat.
415 prev
417 next
418 The prev method changes the date to the previous (or current)
419 occurrence of either a day of the week, a certain time of day, or
420 both. The next method changes the date to the next (or current)
421 occurrence. The examples below illustrate the prev method, but the
422 next one is identical in operation.
423 There are two different ways to use this method. The first is to
425 pass in a day of week and possibly a time:
426 $err = $date->prev($dow, $curr [,$time]);
428 If $curr = 0, this means to look for the previous occurence of the
430 day of week, and set the time to the value passed in (or current
431 time if no time was passed in). The day is ALWAY less than the
432 current day. If the current day is the same day of week as $dow,
433 then the date returned will be one week earlier.
434 If $curr = 1, it means to look for the current or previous
436 occurence of the day of week, and set the time to the value passed
437 in (or 00:00:00 if none was passed in). If the current day of week
438 is the same as $dow, the date will remain unchanged. Since the time
439 is then set, the new date may actually occur after the original
440 date depending on the value of $time.
441 If $curr = 2, it means to look for the last time (not counting now)
443 that the day of week at the given time occurred. The date may be
444 the same as the original date.
445 $time may be a list reference of [H,MN,S], [H,MN], or [H].
447 The following examples should illustrate the use of this function.
449 Original Date = Fri Nov 22 18:15:00
451 dow curr time new date
453 4 (Thu) 0/1/2 undef Thu Nov 21 00:00:00
455 4 0/1/2 [12,30,0] Thu Nov 21 12:30:00
456 5 (Fri) 0/2 undef Fri Nov 15 18:15:00
458 5 1 undef Fri Nov 22 18:15:00
459 5 0 [12,30,0] Fri Nov 15 12:30:00
461 5 1/2 [12,30,0] Fri Nov 22 12:30:00
462 5 0/2 [19,30,0] Fri Nov 15 19:30:00
464 5 1 [19,30,0] Fri Nov 22 19:30:00
465 The second way to use this method is by passing in undef for the
467 day of week.
468 $err = $date->prev(undef,$curr,$time);
470 In this case, a time is required and it must be a list reference of
472 3 elements: [H, MN, S]. Any or all of the elements may be undef.
473 The new date is the previous occurrence of the time.
475 If you define hours, then minutes and seconds may be defined, or
477 default to 0 and you are looking for a previous time that the
478 specified time (HH:00:00) occurred (which might be as much as 24
479 hours in the past).
480 If hours are undefined and minutes are defined, then seconds may be
482 defined, or default to 0, and you are looking for the last time the
483 minutes/seconds (MN:SS) appeared on the digital clock, which will
484 be sometime in the past hour.
485 Finally, if hours and minutes are undefined, seconds must be
487 defined (or default to zero) and the last time that that second
488 occurred will be returned (which will be sometime in the past
489 minute).
490 If $curr is non-zero, the current time is returned if it matches
492 the criteria passed in, so the returned value will be now or in the
493 past. If $curr is zero, the time returned will definitely be in
494 the past.
495 DATE = Fri Nov 22 18:15:00
497 curr hr min sec returns
499 0/1 18 undef undef Nov 22 18:00:00
500 0/1 18 30 0 Nov 21 18:30:00
501 0 18 15 undef Nov 21 18:15:00
502 1 18 15 undef Nov 22 18:15:00
503 0 undef 15 undef Nov 22 17:15:00
504 1 undef 15 undef Nov 22 18:15:00
505 printf
507 $out = $date->printf($in);
508 @out = $date->printf(@in);
509 This takes a string or list of strings which may contain any number
511 of special formatting directives. These directives are replaced
512 with information contained in the date. Everything else in the
513 string is returned unmodified.
514 A directive always begins with '%'. They are described in the
516 section below in the section PRINTF DIRECTIVES.
517 secs_since_1970_GMT
519 $secs = $date->secs_since_1970_GMT();
520 This returns the number of seconds that have elapsed since Jan 1,
522 1970 00:00:00 GMT (negative if the date is earlier).
523 The reverse is also allowed:
525 $err = $date->secs_sincs_1970_GMT($secs);
527 which sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT
529 in the local time zone.
530 set
532 $err = $date->set($field,@vals [,$isdst]);
533 This explicitly sets one or more fields in a date.
535 $field can be any of the following:
537 $field @vals
539 zone [ZONE] ZONE can be any zone or alias
541 zdate [ZONE,]DATE sets the zone and entire date
543 date DATE sets the entire date
545 time TIME sets the entire time
547 y YEAR sets one field
549 m MONTH
550 d DAY
551 h HOUR
552 mn MINUTE
553 s SECOND
554 Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME
556 is a list reference containing [H,MN,S].
557 ZONE is optional (it defaults to the local zone as defined either
559 by the system clock, or the SetDate or ForceDate config variables).
560 If it is passed in, it can be any zone name, abbreviation, or
561 offset. An offset can be expressed either as a valid offset string,
562 or as a list reference. Refer to the join/split functions of
563 Date::Manip::Base for information on valid offset strings.
564 An optional last argument is $isdst (which must be 0 or 1) is
566 included when setting a date which could be in either standard time
567 or daylight saving time. It is ignored in all other situations. If
568 it is not included, and the resulting date could be in either, it
569 will default to standard time.
570 The $date object must contain a valid date (unless the entire date
572 is being set with $field set to either "zdate" or "date").
573 If $field is "zone", the time zone of the date will be set. If ZONE
575 is not passed in, it will be set to the local time zone. When
576 setting the time zone, no conversion is done! Whatever date and
577 time is stored in the $date object prior to this remains
578 unchanged... except it will be that date and time in the new time
579 zone.
580 If $field is "zdate", the entire date and time zone is set. If ZONE
582 is not passed in, it is set to the local time zone.
583 If $field is "date", the entire date will be set, but the time zone
585 of the date will not be changed.
586 If $field is "time", or one of the individual fields, only those
588 fields will be modified.
589 An error is returned if an invalid argument list is passed in, or
591 if the resulting date is checked and found to be invalid.
592 value
594 $val = $date->value([$type]);
595 @val = $date->value([$type]);
596 These return the value of the date stored in the object.
598 In scalar context, a printable string in the form YYYYMMDDHH:MN:SS
600 is returned. In list context, a list is returned of (Y,M,D,H,MN,S).
601 If $type is omitted, the date is returned in the time zone it was
603 parsed in.
604 If $type is "local", it is returned in the local time zone (which
606 is either the system time zone, or the zone specified with the
607 SetDate or ForceDate config variables).
608 If $type is "gmt", the date is returned in the GMT time zone.
610 An empty string or list is returned i the case of an error (and an
612 error code is set).
613 week_of_year
615 $wkno = $date->week_of_year([$first]);
616 This figures out the week number. If $first is passed in, it must
618 be between 1 and 7 and refers to the first day of the week. If
619 $first is not passed in, the FirstDay config variable is used.
620 NOTE: This routine should only be called in rare cases. Use printf
622 with the %W, %U, %J, %L formats instead. This routine returns a
623 week between 0 and 53 which must then be "fixed" to get into the
624 ISO 8601 weeks from 1 to 53. A date which returns a week of 0
625 actually belongs to the last week of the previous year. A date
626 which returns a week of 53 may belong to the first week of the next
627 year.
628
630 The following issues may occur when parsing dates that should be
631 understood to make full use of this module.
632 Complete vs. truncated dates and times
634 Date formats are either complete or truncated. A complete date
635 fully specifies the year, month, and day and a complete time fully
636 specifies the hour, minute, and second.
637 It should be understood that in many instances, the information may
639 be implied rather than explicitly stated, but it is still treated
640 as complete.
641 For example, the date "January 3" is complete because it implies
643 the current year.
644 A truncated calendar date or time does not include information
646 about some of the fields. Date::Manip will never work with a
647 partial date or time, so defaults will be supplied.
648 For example, the date "2009-01" is missing a day field, so a
650 default will be used. In this case, the day will be the 1st, so
651 this is equivalent to "Jan 1st 2009". If only the year is given, it
652 will default to Jan 1.
653 If the time, or any of it's components is missing, they default to
655 00. So the time "12:30" and "12:30:00" are equivalent.
656 The "complete" method can be used to check what type of date was
658 parsed, and which values were specified (either explicitly or
659 implied) and which were provided as a default. It should be noted
660 that there is no way to differentiate between an explicit and
661 implied value.
662 A string with a date and/or time may consist of any of the
664 following:
665 a complete date and a time (complete or truncated)
667 a truncated date with no time
668 a time (complete or truncated) with no date
669 In other words, the date "Jan 2009 12:30" is not valid since it
671 consists of a time with a truncated date.
672
674 When specifying a time zone, it can be done in three different ways.
675 One way is to specify the actual time zone. The second is to supply a
676 valid time zone abbreviation. The third is to specify an offset (with
677 an optional abbreviation). The following dates illustrate the these
678 formats.
679 The timezone information always follows the time immediately, and may
681 only be included if a time is included. The following examples use an
682 ISO 8601 format for the date/time, but any of the other date and time
683 formats may be used.
684 The first way to specify the time zone is to specify it by complete
686 name (or using one of the standard aliases):
687 2001-07-01-00:00:00 America/New_York
689 Although this is unambiguous when it comes to determining the time
691 zone, the time is ambiguous in most zones for one hour of the year.
692 When a time change occurs during which the clock is moved back, the
693 same wallclock time occurs twice.
694 For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in
696 the morning, the clock was set back to 01:00. As a result, the date Nov
697 2, 2008 at 01:30 is ambiguous. It is impossible to determine if this
698 refers to the 01:30 that occurred half an hour before the time change,
699 or the one 30 minute after the change.
700 In practice, if this form is used, the date will be assigned to
702 standard time, meaning that there will be some times (typically 1 hour
703 per year) which cannot be expressed this way. As such, this method is
704 discouraged.
705 The second way to specify the time zone, which is the most common, is
707 to use a time zone abbreviation:
708 2001-07-01-00:00:00 EDT
710 Unfortunately, the abbreviation does not uniquely determine the time
712 zone except in a few cases. In order to assign a time zone, Date::Manip
713 will refer to a list of all time zones which use the abbreviation.
714 They will be tested, in the order given in the Date::Manip::Zones
715 documentation, and the first match (i.e. the one in which the given
716 date/time and abbreviation are valid) determines the time zone which
717 will be used. A great deal of effort has been made to ensure that the
718 most likely time zone will be obtained (i.e. the most common time zones
719 are tested before less common ones), so in most cases, the desired
720 results will be obtained.
721 If the default order does not yield the desired time zone, the order of
723 testing can be modified using the abbrev method described in the
724 Date::Manip::TZ documentation.
725 Although the time zone is ambiguous, the date is not, since only time
727 zones for which the date are valid will be used.
728 The third way to specify the time zone is by specifying an offset and
730 an optional abbreviation:
731 2001-07-01-00:00:00 -04
733 2001-07-01-00:00:00 -0400
734 2001-07-01-00:00:00 -040000
735 2001-07-01-00:00:00 -04:00
736 2001-07-01-00:00:00 -04:00:00
737 2001-07-01-00:00:00 -04 (EDT)
739 2001-07-01-00:00:00 -0400 (EDT)
740 2001-07-01-00:00:00 -040000 (EDT)
741 2001-07-01-00:00:00 -04:00 (EDT)
742 2001-07-01-00:00:00 -04:00:00 (EDT)
743 The offset almost never sufficient to uniquely determine the time zone
745 (and it is not even guaranteed that both the offset and abbreviation
746 will, though in practice, it is probably sufficient). In this instance,
747 the time zone will be determined by testing all time zones which have
748 the given offset (and abbreviation if it is included) until one is
749 found which matches both pieces of information. For more information
750 about how this testing is done, refer to the def_zone method of the
751 Date::Manip::TZ documentation.
752
754 There are several categories of date formats supported by Date::Manip.
755 These are strings which specify only the year/month/day fields.
756 These formats explicitly set the date, but not the time. These formats
758 may be combined with a time string (as specified below) to set both the
759 date and time. If this is not done, the default time is determined by
760 the DefaultTime config variable.
761 ISO 8601 dates
763 The preferred date formats are those specified by ISO 8601. The
764 specification includes valid calendar date and valid time formats.
765 Date::Manip will handle all of these formats, but does not require
766 that the dates rigidly adhere to the specification since the
767 ultimate goal of Date::Manip is to handle dates as they are
768 represented in real life and some common variations exist which are
769 similar to, but not identical to, those from the specification.
770 A calendar date includes the following fields:
772 CC 2-digit representation of the century
774 YY 2-digit representation of the year in
775 a century
776 MM 2-digit representation of a month
777 DD 2-ditit representation of a day of month
778 DoY 3-digit representation of a day of year
779 (001-366)
780 Www the character "W" followed by a 2-digit
781 week of the year (01-53)
782 D the day of the week (1-7)
783 The following date formats are considered complete by Date::Manip.
785 In the following, the date Thu Mar 5 2009 is used as an example.
786 This is the 64th day of the year. Thu is the 4th day of the week.
787 The week starting Mon, Mar 2 is the 10th week of the year
788 (according the the ISO 8601 definition). Obviously, some of the
789 formats are only valid when used at some times. For example, the
790 format --MMDD refers to a month and day in the current year, so the
791 date Mar 5, 2009 can only be specified using this format during
792 2009.
793 Format Notes Examples
795 CCYYMMDD 20090305
797 CCYY-MM-DD 2009-03-05
798 YYMMDD 1,2,4 090305
800 YY-MM-DD 09-03-05
801 -YYMMDD 3,4 -090305
803 -YY-MM-DD -09-03-05
804 --MMDD 1 --0305
806 --MM-DD --03-05
807 ---DD 1 ---05
809 CCYYDoY 2009064
812 CCYY-DoY 2009-064
813 YYDoY 1,4 09064
815 YY-DoY 09-064
816 -YYDoY 3,4 -09064
818 -YY-DoY -09-064
819 -DoY 1 -064
821 CCYYWwwD 2009W104
824 CCYY-Www-D 2009-W10-4
825 YYWwwD 1,4 09W104
827 YY-Www-D 09-W10-4
828 -YYWwwD 3,4 -09W104
830 -YY-Www-D -09-W10-4
831 -YWwwD 1 -9W104
833 -Y-Www-D -9-W10-4
834 Y is the year (0-9) in
835 current decade
836 -WwwD 1 -W104
838 -Www-D -W10-4
839 -W-D 1 -W-4
841 D is day (1-7) in
842 current week
843 ---D 1 ---4
845 same as -W-D
846 The following date formats are truncated:
848 CCYY-MM 2 2009-03
850 CCYY 2009
852 CC 2 20
854 -YYMM 4 -0903
856 -YY-MM -09-03
857 -YY 4 -09
859 --MM --03
861 CCYYWww 2009W10
863 CCYY-Www 2009-W10
864 YYWww 4 09W10
866 YY-Www 09-W10
867 -YYWww 3,4 -09W10
869 -YY-Www -09-W10
870 -Www -W10
872 Notes:
874 1 These formats are considered truncated in the standard, but
876 since
877 they do include (or imply, using the current date for defaults)
878 all of
879 the fields, and since they do not introduce any parsing
880 complexities,
881 the standard is relaxed, and they are treated as complete.
882 2 These formats are treated differently than in Date::Manip 5.xx
884 as
885 described below.
886 3 These formats are not defined in the ISO 8601 spec, but
888 are added for the sake of completeness since they do not
889 add any parsing incompatibilities.
890 4 Formats where the century is not given are described as a year
892 in
893 the current century in the specification. Date::Manip treats
894 this
895 more generically using the YYtoYYYY config variable. This will
896 be
897 used to determine how to determine the full year.
898 Date::Manip 5.xx handled ISO 8601 dates in a less rigid fashion,
900 and deviated from the specification in several formats. As of 6.00,
901 the specification is followed much more closely so that all of the
902 date formats included in it should produce valid dates. This
903 changes, in a backwards incompatible way, the way a few strings
904 will be interpreted as dates.
905 As of 6.00, a two-digit date will be treated as CC. Previously, it
907 was treated as YY.
908 A six-digit date will be treated as YYMMDD. Previously, it was
910 treated as YYYYMM.
911 Previously, dashes were treated as optional in many cases.
913 According to the specification, dates may be written in expanded
914 form (with all dashes present) or abbreviate form (with no dashes).
915 As of 6.00, this is the behavior, so the formats: YYMMDD and YY-MM-
916 DD are allowed, as per the specification, but the format YY-MMDD is
917 NOT allowed (though it was previously).
918 The Www-D formats require a bit of explanation. According to the
920 specification, the date:
921 1996-w02-3
923 refers to the day with an ordinal number of 3 within the calendar
925 week in the 2nd week of 1996.
926 In the specification, the days of the week are numbered from 1 to 7
928 (Monday to Sunday), and the week always begins on Monday, so day 1
929 (Monday) is always the first day of the week, day 2 (Tuesday) is
930 always the second day of the week, etc.
931 In Date::Manip, the constraint that the week must start with Monday
933 is relaxed, allowing the week to begin with Sunday (a far more
934 common start of the week in calendars, at least in some parts of
935 the world).
936 This presents a problem though in that the above date could be
938 interpreted as Wednesday (day 3) of the 2nd week of 1996, or as the
939 3rd day of the 2nd week of 1996 (which would normally be Wednesday,
940 but would be Tuesday if the week begins on Sunday).
941 As of Date::Manip 6.00, the above date will be interpreted as the
943 3rd day of the 2nd week. This is a reversal from Date::Manip 5.xx,
944 but I believe is what the specification would require. For more
945 information, refer to the Date::Manip::Changes document.
946 Common date formats
948 Date::Manip supports a number of common date formats. The following
949 fields may be included in a date:
950 YY 2-digit representation of the year
952 YYYY 4-digit representation of the year
953 M 1- or 2- digit representation of the month
954 MM 2-digit representation of the month
955 D 1- or 2- digit representation of the day
956 DD 2-digit representation of the day
957 mmm The abbreviated or full month name (i.e. Jan)
958 The following date formats are supported:
960 Format Notes Examples
962 M/D 1,2 3/5
964 M/D/YY 1 3/5/09
965 M/D/YYYY 1 3/5/2009
966 YYYY/M/D 2009/3/5
968 mmm/D Mar/5
970 mmm/D/YY Mar/5/09
971 mmm/D/YYYY Mar/5/2009
972 D/mmm 5/Mar
973 D/mmm/YY 5/Mar/09
974 D/mmm/YYYY 5/Mar/2009
975 YYYY/mmm/D 2009/Mar/5
976 mmmD Mar5
978 mmmDDYY Mar0509
979 mmmDDYYYY Mar052009
980 Dmmm 5Mar
981 DmmmYY 5Mar09
982 DmmmYYYY 5Mar2009
983 YYYYmmmD 2009Mar5
984 mmmD YY Mar5 09
986 mmmD YYYY Mar5 2009
987 Dmmm YY 5Mar 09
988 Dmmm YYYY 5Mar 2009
989 mmm/D YY Mar/5 09
991 mmm/D YYYY Mar/5 2009
992 D/mmm YY 5/Mar 09
993 D/mmm YYYY 5/Mar 2009
994 YY mmmD 09 Mar5
996 YYYY mmmD 2009 Mar5
997 YY Dmmm 09 5Mar
998 YYYY Dmmm 2009 5Mar
999 YY mmm/D 09 Mar/5
1001 YYYY mmm/D 2009 Mar/5
1002 YY D/mmm 09 5/Mar
1003 YYYY D/mmm 2009 5/Mar
1004 YYYY:MM:DD 2010:01:15 (EXIF format)
1006 In the formats above, the slash (/) can be replace by any of the
1008 valid separators: whitespace, slash (/), period (.), or dash (-).
1009 The dash, though allowed, is discouraged since it may conflict with
1010 an ISO 8601 format. For example, the format MM/DD/YY is just fine,
1011 but MM-DD-YY does not work since it conflicts with YY-MM-DD. To be
1012 safe, if "-" is used as a separator in a non-ISO format, they
1013 should be turned into "/" before calling the Date::Manip routines.
1014 No matter what separator is used, the same separator must be used
1016 throughout the date. For example, MM/DD/YY is valid and MM.DD.YY is
1017 also valid, but MM/DD.YY is NOT valid.
1018 Notes:
1020 1 With these formats, Americans tend to write month first, but
1022 many
1023 other countries tend to write day first. The latter behavior
1024 can be
1025 obtained by setting the config variable DateFormat to something
1026 other
1027 than "US".
1028 2 The dot (.) separator may not be used in the M/D format since it
1030 will be interpreted as the H12,H+ format described below.
1031 These formats explicitly set the date, but not the time. The
1033 default time is determined by the DefaultTime config variable.
1034 Less common date formats
1036 The following formats are also supported by Date::Manip:
1037 DoW
1039 The day of week of the current week
1040 Friday
1041 Friday at 12:40
1042 MMM Nth [YYYY]
1044 Nth MMM [YYYY]
1045 YYYY MMM Nth
1046 YYYY Nth MMM
1047 Dec 1st 1970
1048 1st Dec 1970
1049 1970 Dec 1st
1050 1970 1st Dec
1051 next/prev DoW
1053 The next or last occurence of DoW
1054 next Friday
1055 last Friday at 12:40
1056 next/last week/month/year
1058 The day one week/month/year from now
1059 or in the past
1060 next week
1061 last month at 15:00
1062 last day in MMM [YYYY]
1064 The last day of the month
1065 last day in October
1066 last day in October 1996
1067 last DoW in MMM [YYYY]
1069 The last DoW in the month
1070 last Tuesday in October
1071 last Tuesday in October 1996
1072 last DoW in YYYY
1074 The last DoW in the year
1075 last Tuesday in 1997
1076 NOTE: "last DoW" doesn't work in
1078 English since the word "last"
1079 is used for both this expression
1080 and for "prev DoW", which gets
1081 parsed first. "last DoW" MAY
1082 work in other languages.
1083 Nth DoW in MMM [YYYY]
1085 The Nth DoW in the month
1086 3rd Tuesday in October
1087 3rd Tuesday in October 1996
1088 Nth DoW [YYYY]
1090 The Nth DoW in the year
1091 22nd Sunday
1092 22nd Sunday in 1996
1093 DoW week
1095 British: same as "in 1 week on DoW"
1096 Monday week
1097 DoW week N [YYYY]
1099 Dow Nth week [YYYY]
1100 Sunday week 22
1101 Sunday 22nd week
1102 These refer to the day of week
1103 of the Nth week of the year.
1104 Nth
1106 12th
1107 This refers to the Nth day of the
1108 current month.
1109 Note that the formats "Sunday week 22" and "22nd Sunday" give
1111 different behaviors. "Sunday week 22" returns the Sunday of the
1112 22nd week of the year based on how week 1 is defined. ISO 8601
1113 defines week one to contain Jan 4, so "Sunday week 1" might be the
1114 first or second Sunday of the current year, or the last Sunday of
1115 the previous year. "22nd Sunday" gives the actual 22nd time Sunday
1116 occurs in a given year, regardless of the definition of a week.
1117 Special date strings
1119 Most languages have strings which can be used to specify the date
1120 (relative to today). In English, these include the strings:
1121 today
1123 tomorrow
1124 yesterday
1125 There is also support for the British formats:
1127 today week
1129 tomorrow week
1130 yesterday week
1131 which refer to one week after today/tomorrow/yesterday
1133 respectively.
1134 Other languages have similar strings.
1136 In all of the formats (except for ISO 8601 formats), the day of week
1138 ("Friday") can be entered anywhere in the date and it will be checked
1139 for accuracy. In other words,
1140 "Tue Jul 16 1996 13:17:00"
1142 will work but
1144 "Jul 16 1996 Wednesday 13:17:00"
1146 will not (because Jul 16, 1996 is Tuesday, not Wednesday).
1148
1150 There are several categories of time formats supported by Date::Manip.
1151 These are strings which specify only the hour/minute/second fields.
1152 ISO 8601 times
1154 A time may be also be complete or truncated. Again, Date::Manip
1155 treats some formats as complete even though the specification calls
1156 them truncated.
1157 A time may include the following fields:
1159 HH 2-digit representation of the hour
1161 MN 2-digit representation of the minutes
1162 SS 2-digit representation of the seconds
1163 H+ 1+ digit representation of fractional hours
1164 M+ 1+ digit representation of fractional minutes
1165 S+ 1+ digit representation of fractional seconds
1166 The following time formats are considered complete by Date::Manip.
1168 The time 12:30:15 will be expressed in the examples.
1169 Format Notes Examples
1171 HHMNSS 2 123015
1173 HH:MN:SS 12:30:15
1175 HHMNSS,S+ 123015,5
1177 HH:MN:SS,S+ 12:30:15,5
1178 Fractional seconds are ignored
1179 HHMN,M+ 1230,25
1181 HH:MN,M+ 12:30,25
1182 This is 12:30:00 + 0.25 minutes
1183 HH,H+ 12,5
1185 This is 12:00:00 + 0.5 hours, so
1186 this is equivalent to 12:30:00
1187 -MNSS 1 -3015
1189 -MN:SS -30:15
1190 --SS 1 --15
1192 -MNSS,S+ 1 -3015,5
1194 -MN:SS,S+ -30:15,5
1195 -MN,M+ 1 -30,25
1197 --SS,S+ 1 --15,5
1199 HHMN 3 1230
1201 HH:MN 12:30
1202 The following time formats are truncated:
1204 HH 12
1206 -MN -30
1208 Notes:
1210 1 These formats are considered truncated in the standard, but
1212 since
1213 they do include (or imply, using the current time for defaults)
1214 all of
1215 the fields, and since they do not introduce any parsing
1216 complexities,
1217 the standard is relaxed, and they are treated as complete.
1218 2 The HHMNSS format will not be correctly parsed since it is
1220 impossible
1221 to distinguish between it and YYMMDD. In order to parse an all-
1222 digit
1223 time, add the string ",0" to the end to force it to be
1224 interpreted
1225 as a time or include time zone information (either a zone name
1226 or
1227 abbreviation... an offset will not work in this case).
1228 3 The HH:MN format will be treated as complete, even though it is
1230 incomplete due to missing the seconds. In real life, expressing
1231 a time in the HH:MN format is very common, and is regarded as
1232 complete,
1233 and might include time zone information.
1234 ISO 8601 times may be followed by a time zone. Date::Manip relaxes
1236 the constraints placed on the time zone format and allows any of
1237 the methods used to specify the time zone including time zone name,
1238 abbreviation, or offset. The time zone may be separated from the
1239 time by a space, but it is not required.
1240 Another constraint that is relaxed is that the fractional part may
1242 be specified using a period. In other words, the following are
1243 equivalent:
1244 12:30,25
1246 12:30.25
1247 It should be noted (as it is in the specification) that using a
1249 negative time zone offset may cause confusion. In addition to
1250 visually confusing, it may not be parsed correctly. For example,
1251 the time:
1252 123005-0300
1254 may not be parsed correctly. When using an offset time zone, you
1256 should always use the colon separators in the time:
1257 12:30:05-0300
1259 Other time formats
1261 A time may include any of the following fields:
1262 H24 1- or 2-digit representation of the hour (0-23)
1264 H12 1- or 2-digit representation of the hour (1-12)
1265 MN 2-digit representation of the minutes
1266 SS 2-digit representation of the seconds
1267 H+ 1+ digit representation of fractional hours
1268 M+ 1+ digit representation of fractional minutes
1269 S+ 1+ digit representation of fractional seconds
1270 AM A language specific AM/PM string
1271 The following time formats are accepted:
1273 Format Examples
1275 H24:MN:SS 17:30:15
1277 H12:MN:SS AM 5:30:15 PM
1278 H12:MN:SS
1279 H24:MN:SS,S+ 17:30:15,5
1281 H12:MN:SS,S+ AM 5:30:15,5 PM
1282 H12:MN:SS,S+ Fractional seconds are ignored
1283 H24:MN,M+ 17:30,25
1285 H12:MN,M+ AM 5:30,25 PM
1286 H12:MN,M+ This is 17:30:00 + 0.25 minutes
1287 H24,H+ 17,5
1289 H12,H+ AM 5,5 PM
1290 H12,H+ This is 17:00:00 + 0.5 hours, so
1291 this is equivalent to 17:30:00
1292 H24:MN 17:30
1294 H12:MN AM 5:30 PM
1295 H12:MN
1296 H12 AM 5 PM
1298 The fractional part may be specified using a comma, a period, or a
1300 colon. A language specific fractional separator may also be
1301 available for some languages. A colon will only work if the hour,
1302 minute, and second are all explicitly included, but will not work
1303 otherwise.
1304 In other words, the following are equivalent:
1306 12:30:20,25
1308 12:30:20.25
1309 12:30:20:25
1310 Some languages have alternate H:MN and MN:S separators. For
1312 example, one H:MN separator in French is 'h' (the MN:S separator is
1313 still a colon), so the following are equivalent:
1314 12:30:00
1316 12h30:00
1317 Time zone information can be included immediately following the
1319 time. It can be separated by whitespace from the time, or it can
1320 be immediately adjacent.
1321 Special time strings
1323 Different languages may have some words which can be used to
1324 specify a certain time of day. In English, for example, the
1325 following words are equivalent to the time listed:
1326 noon 12:00:00
1328 midnight 00:00:00
1329 So, the following are equivalent:
1331 Jan 2 2009 at noon
1333 Jan 2 2009 12:00:00
1334 There were two possible ways to interpret midnight. One was at the
1336 start of the day (00:00:00) and the other was at the end of the day
1337 (24:00:00 which would actually mean at 00:00:00 of the following
1338 day). The first has been used to maintain backwards compatibility
1339 with Date::Manip 5.xx .
1340 Other languages have similar strings.
1342 In most languages, a word similar to "at" may precede the time (this
1344 does NOT apply to ISO 8601 time formats). This word (which must be
1345 separate from all other parts of the date with whitespace) is optional,
1346 and the following are equivalent:
1347 12:30
1349 at 12:30
1350 The times "12:00 am", "12:00 pm", and "midnight" are not well defined.
1352 Date::Manip uses the following convention:
1353 midnight = 12:00am = 00:00:00
1355 noon = 12:00pm = 12:00:00
1356 and the day goes from 00:00:00 to 23:59:59. In other words, midnight
1358 is the beginning of a day rather than the end of one. The time
1359 24:00:00 is also allowed (though it is automatically transformed to
1360 00:00:00 of the following day). This gives the unusual result of
1361 parsing:
1362 Wed Feb 8 2006 24:00:00
1364 which gives the date of:
1366 Thu Feb 9 2006 00:00:00
1368
1370 There are several categories of strings which specify both the date and
1371 time. These include the following:
1372 ISO 8601 combined date and time
1374 A combined ISO 8601 date and time is a string containing a complete
1375 ISO 8601 date and a complete or truncated ISO 8601 time.
1376 Date::Manip relaxes the restrictions on how the two are combined.
1378 The time may be separated from the date by space, dash, or the
1379 letter T, or the two may be joined with nothing separating them.
1380 When the time immediately follows the date, or when the two are
1382 separated by a dash, the resulting string MUST be unambiguous.
1383 Provided the date includes all of the dashes in it (i.e. YY-MM-DD
1384 instead of YYMMDD), it is rare that there is any ambiguity. If the
1385 date does not include dashes, the strings may be ambiguous, and in
1386 this case, separating the date and time with a space or the letter
1387 T is useful (and perhaps necessary) to correctly interpret the
1388 string.
1389 The DoY formats should always be separated from the time by
1391 something. They are visually confusing if they are not separated
1392 from the time.
1393 Time zone information can be included immediately following a
1395 complete time. It may not be included if no time is given, or if a
1396 truncated time is included. The time zone may be separated from the
1397 time with whitespace, or it can be immediately adjacent to it
1398 (since the ISO 8601 specification allows it in some cases).
1399 Non-ISO 8601 combined date and time
1401 A date from any of the formats above (except for the ISO 8601
1402 formats) may be combined with any of the time formats above (except
1403 for the ISO 8601 time formats) in any combination to form a valid
1404 combined date and time.
1405 Deltas
1407 Dates are often specified in terms of a delta from "now". For
1408 example, "in 2 days".
1409 Any valid delta can be used to specify a date, and the date is
1411 defined as that delta added to "now". Refer to the
1412 Date::Manip::Delta documentation for a list of valid delta formats.
1413 If the delta itself does not include a time part, the time may be
1415 specified explicitly. For example:
1416 in 3 days at 12:00:00
1418 will take the delta part "in 3 days" and add it to the current
1420 time, then set the time to 12:00:00.
1421 It is NOT allowed to include an explicit time if any time segment
1423 was included in the delta. For example, the following is invalid:
1424 in 3 days 2 hours at 12:00:00
1426 One additional format that is supported is to include only week (or
1428 higher) components in the delta and to set the day of week. For
1429 example:
1430 Friday in 2 weeks
1432 in 2 weeks on Friday
1433 Friday 2 weeks ago
1434 2 weeks ago on Friday at 13:45
1435 These first apply the delta (of weeks, months, and years) to the
1437 current time, and then set the day to the given day-of-week in that
1438 week.
1439 Special date and time strings
1441 Most language have strings which can be used to specify the full
1442 date and time (relative to the current date and time). In English,
1443 these include the string:
1444 now
1446 Addition combined date and time formats
1448 The following formats are also supported:
1449 epoch SECS
1451 The number of seconds since the epoch
1452 (Jan 1, 1970 00:00:00 GMT). SECS may
1453 be negative to give time before the
1454 epoch.
1455 A couple of notes:
1457 Commas may be included in all date formats arbitrarily (except for ISO
1459 8601 formats where they may only be included when allowed by the
1460 specification).
1461 The time/time zone is removed from the date before the date is parsed,
1463 so the time may appear before or after the date, or between any two
1464 parts of the date.
1465 Certain words such as "on", "in", "at", "of", etc. which commonly
1467 appear in a date or time are ignored (except in ISO 8601 formats).
1468
1470 The following printf directives are replaced with information from the
1471 date.
1472 Year
1474 %y year - 00 to 99
1475 %Y year - 0001 to 9999
1476 Month, Week
1478 %m month of year - 01 to 12
1479 %f month of year - " 1" to "12"
1480 %b,%h month abbreviation - Jan to Dec
1481 %B month name - January to December
1482 Day
1484 %j day of the year - 001 to 366
1485 %d day of month - 01 to 31
1486 %e day of month - " 1" to "31"
1487 %v weekday abbreviation - " S"," M"," T", ...
1488 %a weekday abbreviation - Sun to Sat
1489 %A weekday name - Sunday to Saturday
1490 %w day of week - 1 to 7 (1=Monday)
1491 %E day of month with
1492 suffix - 1st, 2nd, 3rd...
1493 Hour
1495 %H hour - 00 to 23
1496 %k hour - " 0" to "23"
1497 %i hour - " 1" to "12"
1498 %I hour - 01 to 12
1499 %p AM or PM
1500 Minute, Second, Time zone
1502 %M minute - 00 to 59
1503 %S second - 00 to 59
1504 %Z time zone abbreviation - EDT
1505 %z time zone as GMT offset - +0100 (see Note 4)
1506 %N time zone as GMT offset - +01:00:00
1507 Epoch (see NOTE 3 below)
1509 %s seconds from
1510 1/1/1970 GMT - negative if before
1511 %o seconds from 1/1/1970
1512 in the current time
1513 zone
1514 Date, Time
1516 %c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
1517 %C,%u %a %b %e %H:%M:%S %Z %Y - Fri Apr 28 17:25:57 EDT 1995
1518 %g %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT
1519 %D %m/%d/%y - 04/28/95
1520 %x %m/%d/%y or %d/%m/%y - 04/28/95 or 28/04/28
1521 (Depends on DateFormat variable)
1522 %l date in ls(1) format (see NOTE 1 below)
1523 %b %e %H:%M - Apr 28 17:23 (*)
1524 %b %e %Y - Apr 28 1993 (*)
1525 %r %I:%M:%S %p - 05:39:55 PM
1526 %R %H:%M - 17:40
1527 %T,%X %H:%M:%S - 17:40:58
1528 %V %m%d%H%M%y - 0428174095
1529 %Q %Y%m%d - 19961025
1530 %q %Y%m%d%H%M%S - 19961025174058
1531 %P %Y%m%d%H:%M:%S - 1996102517:40:58
1532 %O %Y-%m-%dT%H:%M:%S - 1996-10-25T17:40:58
1533 %F %A, %B %e, %Y - Sunday, January 1, 1996
1534 %K %Y-%j - 1997-045
1535 Special Year/Week formats (see NOTE 2 below)
1537 %G year, Monday as first
1538 day of week - 0001 to 9999
1539 %W week of year, Monday
1540 as first day of week - 01 to 53
1541 %L year, Sunday as first
1542 day of week - 0001 to 9999
1543 %U week of year, Sunday
1544 as first day of week - 01 to 53
1545 %J %G-W%W-%w - 1997-W02-2
1546 Other formats
1548 %n insert a newline character
1549 %t insert a tab character
1550 %% insert a `%' character
1551 %+ insert a `+' character
1552 All other characters are currently unused, but may be used in the
1554 future. They currently insert the character following the %,
1555 If a lone percent is the final character in a format, it is ignored.
1557 The formats used in this routine were originally based on date.pl
1559 (version 3.2) by Terry McGonigal, as well as a couple taken from
1560 different versions of the Solaris date(1) command. Also, several have
1561 been added which are unique to Date::Manip.
1562 NOTE 1:
1564 The ls format (%l) applies to date within the past OR future 6 months!
1566 Any date that is before the date NOW - 6 months, or that is on or after
1567 the date NOW + 6 months will have the year printed out.
1568 The later time must be on or after so that there is no ambiguity. If it
1570 is now 2000-06-06-12:00:00, then the date 1999-12-06-12:00:00 will be
1571 written as "Dec 6 12:00" but the date 2000-12-06-12:00:00 will be
1572 written as "Dec 6 2000".
1573 NOTE 2:
1575 The %U, %W, %L, %G, and %J formats are used to support the ISO-8601
1577 format: YYYY-wWW-D. In this format, a date is written as a year, the
1578 week of the year, and the day of the week. Technically, the week may
1579 be considered to start on any day of the week, but Sunday and Monday
1580 are the both common choices, so both are supported.
1581 The %W and %G formats return the week-of-year and the year treating
1583 weeks as starting on Monday.
1584 The %U and %L formats return the week-of-year and the year treating
1586 weeks as starting on Sunday.
1587 Most of the time, the %L and %G formats returns the same value as the
1589 %Y format, but there is a problem with days occurring in the first or
1590 last week of the year.
1591 The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D
1593 format is actually 1992-W53-5. In other words, Jan 1 is treated as
1594 being in the last week of the preceding year. Depending on the year,
1595 days in the first week of a year may belong to the previous year, and
1596 days in the final week of a year may belong to the next year. The week
1597 is assigned to the year which has most of the days. For example, if
1598 the week starts on Sunday, then the last week of 2003 is 2003-12-28 to
1599 2004-01-03. This week is assigned to 2003 since 4 of the days in it
1600 are in 2003 and only 3 of them are in 2004. The first week of 2004
1601 starts on 2004-01-04.
1602 The %U and %W formats return a week-of-year number from 01 to 53. %L
1604 and %G return the corresponding year, and to get this type of
1605 information, you should always use the (%W,%G) combination or (%U,%L)
1606 combination. %Y should not be used as it will yield incorrect results.
1607 %J returns the full ISO-8601 format (%G-W%W-%w).
1609 NOTE 3:
1611 The %s and %o formats return negative values if the date is before the
1613 start of the epoch. Other Unix utilities would return an error, or a
1614 zero, so if you are going to use Date::Manip in conjunction with these,
1615 be sure to check for a negative value.
1616 NOTE 4:
1618 The %z format returns the offset in the RFC 822 specified format +0500
1620 . Most offsets are full hour amounts, so this is not a problem, but
1621 some offsets are irregular (+05:17:30). In this case, the string
1622 returned is +051730 which isn't RFC 822 compliant, but since RFC 822
1623 ignores this situation, I had to decide between returning an incorrect
1624 value, or breaking strict compliance, and I chose the second option.
1625
1627 None known.
1628
1630 Please refer to the Date::Manip::Problems documentation for information
1631 on submitting bug reports or questions to the author.
1632
1634 Date::Manip - main module documentation
1635
1637 This script is free software; you can redistribute it and/or modify it
1638 under the same terms as Perl itself.
1639
1641 Sullivan Beck (sbeck@cpan.org)
1642perl v5.10.1 2011-12-07 Date::Manip::Date(3)