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 is_business_day
83 $flag = $date->is_business_day($checktime);
84 This returns 1 if $date is a business day.
86 $checktime may be passed in. If it is non-zero, the time is checked
88 to see if the date is a business day and falls within work hours.
89 list_holidays
91 @date = $date->list_holidays([$y]);
92 This returns a list of Date::Manip::Date objects containing all
94 dates during a year which are holidays. The times will all be
95 00:00:00.
96 If $y is not passed in, it will list the holidays in the same year
98 as the date stored in $date.
99 list_events
101 @list = $date->list_events( [$format] );
102 @list = $date->list_events(0 [,$format]);
103 @list = $date->list_events($date1 [,$format]);
104 This returns a list of events. Events are defined in the Events
106 section of the config file (discussed in the Date::Manip::Holidays
107 manual).
108 In the first form, a list of all events active at the precise time
110 stored in $date will be returned.
111 If the first argument evaluates to 0, a list of all events active
113 at any time during that day (Y,M,D) are returned.
114 If the first argument is another date object, all events that are
116 active at any time between the two dates (inclusive) are returned.
117 By default, the list returned is of the form:
119 ( [START, END, NAME],
121 [START, END, NAME],
122 ...
123 )
124 where START is a date object when an event starts, END is a date
126 object when it ends, and NAME is the name of the event. Note that
127 START and END are the actual start and end date of the event and
128 may be outside the range of dates being examined (though the event
129 will obviously overlap the range or it wouldn't be included in the
130 list).
131 If $format is included, it can specify an alternate format for the
133 output. Currently, the only supported format is named "dates" and
134 it returns a list in the form:
135 ( [DATE1, NAME1a, NAME1b, ...],
137 [DATE2, NAME2a, NAME2b, ...],
138 ...
139 )
140 This includes a list of all dates during the range when there is a
142 change in what events are active. DATE1 will always be the start of
143 the range being considered, and (NAME1a, NAME1b, ...) are the list
144 of all events that will be active at that time. At DATE2, the list
145 of active events changes with (NAME2a, NAME2b, ...) being active.
146 It is quite possible that a date be included which has no active
148 events, and in that case, the list of names will be empty.
149 nearest_business_day
151 $date->nearest_business_day([$tomorrowfirst]);
152 This looks for the work day nearest to $date. If $date is a work
154 day, it is left unmodified. Otherwise, it will look forward or
155 backwards in time 1 day at a time until a work day is found. If
156 $tomorrowfirst is non-zero (or if it is omitted and the config
157 variable TomorrowFirst is non-zero), we look to the future first.
158 Otherwise, we look in the past first. In other words, in a normal
159 week, if $date is Wednesday, $date is returned. If $date is
160 Saturday, Friday is returned. If $date is Sunday, Monday is
161 returned. If Wednesday is a holiday, Thursday is returned if
162 $tomorrowfirst is non-nil or Tuesday otherwise.
163 next_business_day
165 prev_business_day
166 $date->next_business_day($off [,$checktime]);
167 $date->prev_business_day($off [,$checktime]);
168 The next_business_day method sets the given date to $off (which can
170 be a positive integer or zero) business days in the future. The
171 prev_business_day method sets the date to $off business days in the
172 past.
173 First, $date is tested. If $checktime is nonzero, the date must
175 fall on a business date, and during business hours. If $checktime
176 is zero, the time check is not done, and the date must simply fall
177 on a business date.
178 If the check fails, the date is moved to the start of the next
180 business day (if $checktime is nonzero) or the next business day at
181 the current time (if $checktime is zero). Otherwise, it is left
182 unmodified.
183 Next, if $off is greater than 0, the day $off work days from now is
185 determined.
186 One thing to note for the prev_business_day method is that if $date
188 check fails, the date is set to the next business date, exactly
189 like next_business_day. In other words, if $date is not a business
190 day, the call:
191 $date->prev_business_day(0 [,$checktime]);
193 moves $date forward in time instead of backward which is
195 nonintuitive, but you just have to think of day 0 as being the next
196 business day if $date is not a business day.
197 As a result, the following two calls ALWAYS give the same result:
199 $date->next_business_day(0 [,$checktime]);
201 $date->prev_business_day(0 [,$checktime]);
202 no matter what date is stored in $date.
204 parse
206 $err = $date->parse($string [,@opts]);
207 This parses a string which should include a valid date and stores
209 it in the object. If the string does not include a valid date, an
210 error is returned. Use the err method to see the full error
211 message.
212 A full date may include a calendar date (year, month, day), a time
214 of day (hour, minute, second), and time zone information. All of
215 this can be entered in many different formats.
216 For information on valid date formats, refer to the section VALID
218 DATE FORMATS. For information on valid time zone information, refer
219 to the section VALID TIME ZONE FORMATS.
220 If no time zone information is included in the date, it is treated
222 as being in the local time zone.
223 If time zone information is included, the date will be kept in that
225 time zone, and all operations will be done in that time zone. The
226 convert method can be used to change the time zone to the local
227 time zone, or to another time zone.
228 Some things to note:
230 All strings are case insensitive. "December" and "DEceMBer" are
232 equivalent.
233 When a part of the date is not given, defaults are used. This is
235 described below in the section "Complete vs. truncated dates and
236 times".
237 The year may be entered as 2 or 4 digits. If entered as 2 digits,
239 it will be converted to a 4 digit year. There are several ways to
240 do this based on the value of the YYtoYYYY config variable. Refer
241 to the Date::Manip::Config documentation for more details.
242 Dates are always checked to make sure they are valid.
244 If any other arguments are passed in, they act as options which may
246 improve the speed of parsing. These include:
247 noiso8601 Do not try to parse the
249 date as an ISO 8601 date
250 or time.
251 nodow Do not try to parse a
252 day-of-week (Monday) in
253 the string.
254 nocommon Do not try to parse the
255 date using the formats
256 in the "Common date
257 formats" section.
258 noother Do not try to parse the
259 date using the "Less common
260 date formats" or a time
261 using the "Other time
262 formats".
263 nospecial Do not try to parse the
264 date using the "Special
265 date strings" formats
266 or a time using the
267 "Special time strings"
268 formats, or as a
269 combined date/time using
270 the "Additional combined
271 date and time" formats.
272 nodelta Do not treat deltas as
273 a date relative to now.
274 parse_date
276 $err = $date->parse_date($string [,@opts]);
277 This parses a string which contains a valid date and sets the date
279 part of the object.
280 If the object contained a valid date, the time is kept unchanged.
282 If the object did NOT contain a valid date, a time of 00:00:00 is
283 used.
284 @opts can be any of the strings described in the parse method
286 above.
287 parse_time
289 $err = $date->parse_time($string);
290 This parses a string and sets the time portion of $date to contain
292 it.
293 If the object contained a valid date, the Y/M/D portion is left
295 unchanged. Otherwise, the current date is used.
296 parse_format
298 $err = $date->parse_format($format,$string);
299 This will parse a date contained in $string based on explicit
301 format information contained in $format.
302 If the format is invalid, $err will contain an error message. If
304 the format is valid, but string doesn't match, an error code of 1
305 is returned.
306 $format is a string containing a regular expression with some
308 special directives (based on the printf directives). These
309 directives are turned into regular expression components, and then
310 the entire string is turned into a regular expression which, if
311 $string matches it, will return the date.
312 The directives available are identical to the printf directives.
314 So, if your $format string contains the directive '%Y', it will
315 match a 4-digit year.
316 All of the printf directives are available, but with a few
318 simplifications:
319 %l This directive is NOT available.
321 %b,%h,%B will all match a month name or
323 abbreviation
324 %v,%a,%A will all match a day abbreviation
326 or name
327 %z,%Z,%N will match any time zone string
329 %n currently not allowed (multi-line
331 matching not currently supported)
332 The format string may not over-specify the date. In other words,
334 you may not include both a %y and %Y directive or both a %j and %m
335 directive.
336 A valid format string will specify any of the following sets of
338 data:
339 Required Optional
341 M D H Mn S Y Zone Day-of-week
343 M D H Mn Y Zone Day-of-week
344 M D Y Zone Day-of-week
345 H Mn S Zone
346 H Mn Zone
347 For example, if you had a date stored as:
349 YYYY.MM-DD
351 you could match it using the following:
353 $date->parse_format('%Y\\.%m\\-%d',$string);
355 If you wanted to extract the date from an apache log line:
357 10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] "GET /favicon.ico ...
359 you could use:
361 $date->parse_format('.*?\\[%d/%b/%Y:%T %z\\].*',$line);
363 In your format string, you may use capture buffers that can be back
365 referenced elsewhere in the regular expression. If you use numbered
366 back references, just be aware that all of the directives create a
367 single capture buffer (except for the directives like %% which
368 match a special character instead of a portion of a date). If you
369 use named buffers, do NOT use any of the following as they will
370 conflict with the capture buffers created with the standard
371 directives:
372 y
374 m
375 d
376 h
377 mn
378 s
379 mon_name
380 mon_abb
381 dow_name
382 dow_abb
383 dow_char
384 dow_num
385 doy
386 nth
387 ampm
388 epochs
389 epocho
390 tzstring
391 off
392 abb
393 zone
394 g
395 w
396 l
397 u
398 To be safe, it is suggested that named capture buffers start with a
400 capital letter.
401 There is one other caveat if the %x directive is used. The format
403 is converted to a regular expression and then cached (so that a
404 format can be reused without the penalty of doing the conversion to
405 a regular expression, so if you need to set the DateFormat config
406 variable (which determines the meaning of the %x directive), it
407 must be done before a format string containing %x is used. If the
408 DateFormat config variable is set afterwards, the format string
409 will reflect the old, NOT THE NEW, value of DateFormat.
410 prev
412 next
413 The prev method changes the date to the previous (or current)
414 occurrence of either a day of the week, a certain time of day, or
415 both. The next method changes the date to the next (or current)
416 occurrence. The examples below illustrate the prev method, but the
417 next one is identical in operation.
418 There are two different ways to use this method. The first is to
420 pass in a day of week and possibly a time:
421 $err = $date->prev($dow, $curr [,$time]);
423 If $curr = 0, this means to look for the previous occurence of the
425 day of week, and set the time to the value passed in (or current
426 time if no time was passed in). The day is ALWAY less than the
427 current day. If the current day is the same day of week as $dow,
428 then the date returned will be one week earlier.
429 If $curr = 1, it means to look for the current or previous
431 occurence of the day of week, and set the time to the value passed
432 in (or 00:00:00 if none was passed in). If the current day of week
433 is the same as $dow, the date will remain unchanged. Since the time
434 is then set, the new date may actually occur after the original
435 date depending on the value of $time.
436 If $curr = 2, it means to look for the last time (not counting now)
438 that the day of week at the given time occurred. The date may be
439 the same as the original date.
440 $time may be a list reference of [H,MN,S], [H,MN], or [H].
442 The following examples should illustrate the use of this function.
444 Original Date = Fri Nov 22 18:15:00
446 dow curr time new date
448 4 (Thu) 0/1/2 undef Thu Nov 21 00:00:00
450 4 0/1/2 [12,30,0] Thu Nov 21 12:30:00
451 5 (Fri) 0/2 undef Fri Nov 15 18:15:00
453 5 1 undef Fri Nov 22 18:15:00
454 5 0 [12,30,0] Fri Nov 15 12:30:00
456 5 1/2 [12,30,0] Fri Nov 22 12:30:00
457 5 0/2 [19,30,0] Fri Nov 15 19:30:00
459 5 1 [19,30,0] Fri Nov 22 19:30:00
460 The second way to use this method is by passing in undef for the
462 day of week.
463 $err = $date->prev(undef,$curr,$time);
465 In this case, a time is required and it must be a list reference of
467 3 elements: [H, MN, S]. Any or all of the elements may be undef.
468 The new date is the previous occurrence of the time.
470 If you define hours, then minutes and seconds may be defined, or
472 default to 0 and you are looking for a previous time that the
473 specified time (HH:00:00) occurred (which might be as much as 24
474 hours in the past).
475 If hours are undefined and minutes are defined, then seconds may be
477 defined, or default to 0, and you are looking for the last time the
478 minutes/seconds (MN:SS) appeared on the digital clock, which will
479 be sometime in the past hour.
480 Finally, if hours and minutes are undefined, seconds must be
482 defined (or default to zero) and the last time that that second
483 occurred will be returned (which will be sometime in the past
484 minute).
485 If $curr is non-zero, the current time is returned if it matches
487 the criteria passed in, so the returned value will be now or in the
488 past. If $curr is zero, the time returned will definitely be in
489 the past.
490 DATE = Fri Nov 22 18:15:00
492 curr hr min sec returns
494 0/1 18 undef undef Nov 22 18:00:00
495 0/1 18 30 0 Nov 21 18:30:00
496 0 18 15 undef Nov 21 18:15:00
497 1 18 15 undef Nov 22 18:15:00
498 0 undef 15 undef Nov 22 17:15:00
499 1 undef 15 undef Nov 22 18:15:00
500 printf
502 $out = $date->printf($in);
503 This takes a string ($in) which may contain any number of special
505 formatting directives. These directives are replaced with
506 information contained in the date. Everything else in the string is
507 returned unmodified.
508 A directive always begins with '%'. They are described in the
510 section below in the section PRINTF DIRECTIVES.
511 secs_since_1970_GMT
513 $secs = $date->secs_since_1970_GMT();
514 This returns the number of seconds that have elapsed since Jan 1,
516 1970 00:00:00 GMT (negative if the date is earlier).
517 The reverse is also allowed:
519 $err = $date->secs_sincs_1970_GMT($secs);
521 which sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT
523 in the local time zone.
524 set
526 $err = $date->set($field,@vals [,$isdst]);
527 This explicitly sets one or more fields in a date.
529 $field can be any of the following:
531 $field @vals
533 zone [ZONE] ZONE can be any zone or alias
535 zdate [ZONE,]DATE sets the zone and entire date
537 date DATE sets the entire date
539 time TIME sets the entire time
541 y YEAR sets one field
543 m MONTH
544 d DAY
545 h HOUR
546 mn MINUTE
547 s SECOND
548 Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME
550 is a list reference containing [H,MN,S].
551 ZONE is optional (it defaults to the local zone as defined either
553 by the system clock, or the SetDate or ForceDate config variables).
554 If it is passed in, it can be any zone name, abbreviation, or
555 offset. An offset can be expressed either as a valid offset string,
556 or as a list reference. Refer to the join/split functions of
557 Date::Manip::Base for information on valid offset strings.
558 An optional last argument is $isdst (which must be 0 or 1) is
560 included when setting a date which could be in either standard time
561 or daylight savings time. It is ignored in all other situations. If
562 it is not included, and the resulting date could be in either, it
563 will default to standard time.
564 The $date object must contain a valid date (unless the entire date
566 is being set with $field set to either "zdate" or "date").
567 If $field is "zone", the time zone of the date will be set. If ZONE
569 is not passed in, it will be set to the local time zone. When
570 setting the time zone, no conversion is done! Whatever date and
571 time is stored in the $date object prior to this remains
572 unchanged... except it will be that date and time in the new time
573 zone.
574 If $field is "zdate", the entire date and time zone is set. If ZONE
576 is not passed in, it is set to the local time zone.
577 If $field is "date", the entire date will be set, but the time zone
579 of the date will not be changed.
580 If $field is "time", or one of the individual fields, only those
582 fields will be modified.
583 An error is returned if an invalid argument list is passed in, or
585 if the resulting date is checked and found to be invalid.
586 value
588 $val = $date->value([$type]);
589 @val = $date->value([$type]);
590 These return the value of the date stored in the object.
592 In scalar context, a printable string in the form YYYYMMDDHH:MN:SS
594 is returned. In list context, a list is returned of (Y,M,D,H,MN,S).
595 If $type is omitted, the date is returned in the time zone it was
597 parsed in.
598 If $type is "local", it is returned in the local time zone (which
600 is either the system time zone, or the zone specified with the
601 SetDate or ForceDate config variables).
602 If $type is "gmt", the date is returned in the GMT time zone.
604 An empty string or list is returned i the case of an error (and an
606 error code is set).
607 week_of_year
609 $wkno = $date->week_of_year([$first]);
610 This figures out the week number. If $first is passed in, it must
612 be between 1 and 7 and refers to the first day of the week. If
613 $first is not passed in, the FirstDay config variable is used.
614 NOTE: This routine should only be called in rare cases. Use printf
616 with the %W, %U, %J, %L formats instead. This routine returns a
617 week between 0 and 53 which must then be "fixed" to get into the
618 ISO 8601 weeks from 1 to 53. A date which returns a week of 0
619 actually belongs to the last week of the previous year. A date
620 which returns a week of 53 may belong to the first week of the next
621 year.
622
624 The following issues may occur when parsing dates that should be
625 understood to make full use of this module.
626 Complete vs. truncated dates and times
628 Date formats are either complete or truncated. A complete date
629 fully specifies the year, month, and day and a complete time fully
630 specifies the hour, minute, and second.
631 It should be understood that in many instances, the information may
633 be implied rather than explicitly stated, but it is still treated
634 as complete.
635 For example, the date "January 3" is complete because it implies
637 the current year.
638 A truncated calendar date or time does not include information
640 about some of the fields. Date::Manip will never work with a
641 partial date or time, so defaults will be supplied.
642 For example, the date "2009-01" is missing a day field, so a
644 default will be used. In this case, the day will be the 1st, so
645 this is equivalent to "Jan 1st 2009". If only the year is given, it
646 will default to Jan 1.
647 If the time, or any of it's components is missing, they default to
649 00. So the time "12:30" and "12:30:00" are equivalent.
650 The "complete" method can be used to check what type of date was
652 parsed, and which values were specified (either explicitly or
653 implied) and which were provided as a default. It should be noted
654 that there is no way to differentiate between an explicit and
655 implied value.
656 A string with a date and/or time may consist of any of the
658 following:
659 a complete date and a time (complete or truncated)
661 a truncated date with no time
662 a time (complete or truncated) with no date
663 In other words, the date "Jan 2009 12:30" is not valid since it
665 consists of a time with a truncated date.
666
668 When specifying a time zone, it can be done in three different ways.
669 One way is to specify the actual time zone. The second is to supply a
670 valid time zone abbreviation. The third is to specify an offset (with
671 an optional abbreviation). The following dates illustrate the these
672 formats.
673 The timezone information always follows the time immediately, and may
675 only be included if a time is included. The following examples use an
676 ISO 8601 format for the date/time, but any of the other date and time
677 formats may be used.
678 The first way to specify the time zone is to specify it by complete
680 name (or using one of the standard aliases):
681 2001-07-01-00:00:00 America/New_York
683 Although this is unambiguous when it comes to determining the time
685 zone, the time is ambiguous in most zones for one hour of the year.
686 When a time change occurs during which the clock is moved back, the
687 same wallclock time occurs twice.
688 For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in
690 the morning, the clock was set back to 01:00. As a result, the date Nov
691 2, 2008 at 01:30 is ambiguous. It is impossible to determine if this
692 refers to the 01:30 that occurred half an hour before the time change,
693 or the one 30 minute after the change.
694 In practice, if this form is used, the date will be assigned to
696 standard time, meaning that there will be some times (typically 1 hour
697 per year) which cannot be expressed this way. As such, this method is
698 discouraged.
699 The second way to specify the time zone, which is the most common, is
701 to use a time zone abbreviation:
702 2001-07-01-00:00:00 EDT
704 Unfortunately, the abbreviation does not uniquely determine the time
706 zone except in a few cases. In order to assign a time zone, Date::Manip
707 will refer to a list of all time zones which use the abbreviation.
708 They will be tested, in the order given in the Date::Manip::Zones
709 documentation, and the first match (i.e. the one in which the given
710 date/time and abbreviation are valid) determines the time zone which
711 will be used. A great deal of effort has been made to ensure that the
712 most likely time zone will be obtained (i.e. the most common time zones
713 are tested before less common ones), so in most cases, the desired
714 results will be obtained.
715 If the default order does not yield the desired time zone, the order of
717 testing can be modified using the abbrev method described in the
718 Date::Manip::TZ documentation.
719 Although the time zone is ambiguous, the date is not, since only time
721 zones for which the date are valid will be used.
722 The third way to specify the time zone is by specifying an offset and
724 an optional abbreviation:
725 2001-07-01-00:00:00 -04
727 2001-07-01-00:00:00 -0400
728 2001-07-01-00:00:00 -040000
729 2001-07-01-00:00:00 -04:00
730 2001-07-01-00:00:00 -04:00:00
731 2001-07-01-00:00:00 -04 (EDT)
733 2001-07-01-00:00:00 -0400 (EDT)
734 2001-07-01-00:00:00 -040000 (EDT)
735 2001-07-01-00:00:00 -04:00 (EDT)
736 2001-07-01-00:00:00 -04:00:00 (EDT)
737 The offset almost never sufficient to uniquely determine the time zone
739 (and it is not even guaranteed that both the offset and abbreviation
740 will, though in practice, it is probably sufficient). In this instance,
741 the time zone will be determined by testing all time zones which have
742 the given offset (and abbreviation if it is included) until one is
743 found which matches both pieces of information. For more information
744 about how this testing is done, refer to the def_zone method of the
745 Date::Manip::TZ documentation.
746
748 There are several categories of date formats supported by Date::Manip.
749 These are strings which specify only the year/month/day fields.
750 These formats explicitly set the date, but not the time. These formats
752 may be combined with a time string (as specified below) to set both the
753 date and time. If this is not done, the default time is determined by
754 the DefaultTime config variable.
755 ISO 8601 dates
757 The preferred date formats are those specified by ISO 8601. The
758 specification includes valid calendar date and valid time formats.
759 Date::Manip will handle all of these formats, but does not require
760 that the dates rigidly adhere to the specification since the
761 ultimate goal of Date::Manip is to handle dates as they are
762 represented in real life and some common variations exist which are
763 similar to, but not identical to, those from the specification.
764 A calendar date includes the following fields:
766 CC 2-digit representation of the century
768 YY 2-digit representation of the year in
769 a century
770 MM 2-digit representation of a month
771 DD 2-ditit representation of a day of month
772 DoY 3-digit representation of a day of year
773 (001-366)
774 Www the character "W" followed by a 2-digit
775 week of the year (01-53)
776 D the day of the week (1-7)
777 The following date formats are considered complete by Date::Manip.
779 In the following, the date Thu Mar 5 2009 is used as an example.
780 This is the 64th day of the year. Thu is the 4th day of the week.
781 The week starting Mon, Mar 2 is the 10th week of the year
782 (according the the ISO 8601 definition). Obviously, some of the
783 formats are only valid when used at some times. For example, the
784 format --MMDD refers to a month and day in the current year, so the
785 date Mar 5, 2009 can only be specified using this format during
786 2009.
787 Format Notes Examples
789 CCYYMMDD 20090305
791 CCYY-MM-DD 2009-03-05
792 YYMMDD 1,2,4 090305
794 YY-MM-DD 09-03-05
795 -YYMMDD 3,4 -090305
797 -YY-MM-DD -09-03-05
798 --MMDD 1 --0305
800 --MM-DD --03-05
801 ---DD 1 ---05
803 CCYYDoY 2009064
806 CCYY-DoY 2009-064
807 YYDoY 1,4 09064
809 YY-DoY 09-064
810 -YYDoY 3,4 -09064
812 -YY-DoY -09-064
813 -DoY 1 -064
815 CCYYWwwD 2009W104
818 CCYY-Www-D 2009-W10-4
819 YYWwwD 1,4 09W104
821 YY-Www-D 09-W10-4
822 -YYWwwD 3,4 -09W104
824 -YY-Www-D -09-W10-4
825 -YWwwD 1 -9W104
827 -Y-Www-D -9-W10-4
828 Y is the year (0-9) in
829 current decade
830 -WwwD 1 -W104
832 -Www-D -W10-4
833 -W-D 1 -W-4
835 D is day (1-7) in
836 current week
837 ---D 1 ---4
839 same as -W-D
840 The following date formats are truncated:
842 CCYY-MM 2 2009-03
844 CCYY 2009
846 CC 2 20
848 -YYMM 4 -0903
850 -YY-MM -09-03
851 -YY 4 -09
853 --MM --03
855 CCYYWww 2009W10
857 CCYY-Www 2009-W10
858 YYWww 4 09W10
860 YY-Www 09-W10
861 -YYWww 3,4 -09W10
863 -YY-Www -09-W10
864 -Www -W10
866 Notes:
868 1 These formats are considered truncated in the standard, but
870 since
871 they do include (or imply, using the current date for defaults)
872 all of
873 the fields, and since they do not introduce any parsing
874 complexities,
875 the standard is relaxed, and they are treated as complete.
876 2 These formats are treated differently than in Date::Manip 5.xx
878 as
879 described below.
880 3 These formats are not defined in the ISO 8601 spec, but
882 are added for the sake of completeness since they do not
883 add any parsing incompatibilities.
884 4 Formats where the century is not given are described as a year
886 in
887 the current century in the specification. Date::Manip treats
888 this
889 more generically using the YYtoYYYY config variable. This will
890 be
891 used to determine how to determine the full year.
892 Date::Manip 5.xx handled ISO 8601 dates in a less rigid fashion,
894 and deviated from the specification in several formats. As of 6.00,
895 the specification is followed much more closely so that all of the
896 date formats included in it should produce valid dates. This
897 changes, in a backwards incompatible way, the way a few strings
898 will be interpreted as dates.
899 As of 6.00, a two-digit date will be treated as CC. Previously, it
901 was treated as YY.
902 A six-digit date will be treated as YYMMDD. Previously, it was
904 treated as YYYYMM.
905 Previously, dashes were treated as optional in many cases.
907 According to the specification, dates may be written in expanded
908 form (with all dashes present) or abbreviate form (with no dashes).
909 As of 6.00, this is the behavior, so the formats: YYMMDD and YY-MM-
910 DD are allowed, as per the specification, but the format YY-MMDD is
911 NOT allowed (though it was previously).
912 The Www-D formats require a bit of explanation. According to the
914 specification, the date:
915 1996-w02-3
917 refers to the day with an ordinal number of 3 within the calendar
919 week in the 2nd week of 1996.
920 In the specification, the days of the week are numbered from 1 to 7
922 (Monday to Sunday), and the week always begins on Monday, so day 1
923 (Monday) is always the first day of the week, day 2 (Tuesday) is
924 always the second day of the week, etc.
925 In Date::Manip, the constraint that the week must start with Monday
927 is relaxed, allowing the week to begin with Sunday (a far more
928 common start of the week in calendars, at least in some parts of
929 the world).
930 This presents a problem though in that the above date could be
932 interpreted as Wednesday (day 3) of the 2nd week of 1996, or as the
933 3rd day of the 2nd week of 1996 (which would normally be Wednesday,
934 but would be Tuesday if the week begins on Sunday).
935 As of Date::Manip 6.00, the above date will be interpreted as the
937 3rd day of the 2nd week. This is a reversal from Date::Manip 5.xx,
938 but I believe is what the specification would require. For more
939 information, refer to the Date::Manip::Changes document.
940 Common date formats
942 Date::Manip supports a number of common date formats. The following
943 fields may be included in a date:
944 YY 2-digit representation of the year
946 YYYY 4-digit representation of the year
947 M 1- or 2- digit representation of the month
948 MM 2-digit representation of the month
949 D 1- or 2- digit representation of the day
950 DD 2-digit representation of the day
951 mmm The abbreviated or full month name (i.e. Jan)
952 The following date formats are supported:
954 Format Notes Examples
956 M/D 1,2 3/5
958 M/D/YY 1 3/5/09
959 M/D/YYYY 1 3/5/2009
960 YYYY/M/D 2009/3/5
962 mmm/D Mar/5
964 mmm/D/YY Mar/5/09
965 mmm/D/YYYY Mar/5/2009
966 D/mmm 5/Mar
967 D/mmm/YY 5/Mar/09
968 D/mmm/YYYY 5/Mar/2009
969 YYYY/mmm/D 2009/Mar/5
970 mmmD Mar5
972 mmmDDYY Mar0509
973 mmmDDYYYY Mar052009
974 Dmmm 5Mar
975 DmmmYY 5Mar09
976 DmmmYYYY 5Mar2009
977 YYYYmmmD 2009Mar5
978 mmmD YY Mar5 09
980 mmmD YYYY Mar5 2009
981 Dmmm YY 5Mar 09
982 Dmmm YYYY 5Mar 2009
983 mmm/D YY Mar/5 09
985 mmm/D YYYY Mar/5 2009
986 D/mmm YY 5/Mar 09
987 D/mmm YYYY 5/Mar 2009
988 YY mmmD 09 Mar5
990 YYYY mmmD 2009 Mar5
991 YY Dmmm 09 5Mar
992 YYYY Dmmm 2009 5Mar
993 YY mmm/D 09 Mar/5
995 YYYY mmm/D 2009 Mar/5
996 YY D/mmm 09 5/Mar
997 YYYY D/mmm 2009 5/Mar
998 In the formats above, the slash (/) can be replace by any of the
1000 valid separators: whitespace, slash (/), period (.), or dash (-).
1001 The dash, though allowed, is discouraged since it may conflict with
1002 an ISO 8601 format. For example, the format MM/DD/YY is just fine,
1003 but MM-DD-YY does not work since it conflicts with YY-MM-DD. To be
1004 safe, if "-" is used as a separator in a non-ISO format, they
1005 should be turned into "/" before calling the Date::Manip routines.
1006 No matter what separator is used, the same separator must be used
1008 throughout the date. For example, MM/DD/YY is valid and MM.DD.YY is
1009 also valid, but MM/DD.YY is NOT valid.
1010 Notes:
1012 1 With these formats, Americans tend to write month first, but
1014 many
1015 other countries tend to write day first. The latter behavior
1016 can be
1017 obtained by setting the config variable DateFormat to something
1018 other
1019 than "US".
1020 2 The dot (.) separator may not be used in the M/D format since it
1022 will be interpreted as the H12,H+ format described below.
1023 These formats explicitly set the date, but not the time. The
1025 default time is determined by the DefaultTime config variable.
1026 Less common date formats
1028 The following formats are also supported by Date::Manip:
1029 DoW
1031 The day of week of the current week
1032 Friday
1033 Friday at 12:40
1034 MMM Nth [YYYY]
1036 Nth MMM [YYYY]
1037 YYYY MMM Nth
1038 YYYY Nth MMM
1039 Dec 1st 1970
1040 1st Dec 1970
1041 1970 Dec 1st
1042 1970 1st Dec
1043 next/prev DoW
1045 The next or last occurence of DoW
1046 next Friday
1047 last Friday at 12:40
1048 next/last week/month/year
1050 The day one week/month/year from now
1051 or in the past
1052 next week
1053 last month at 15:00
1054 last day in MMM [YYYY]
1056 The last day of the month
1057 last day in October
1058 last day in October 1996
1059 last DoW in MMM [YYYY]
1061 The last DoW in the month
1062 last Tuesday in October
1063 last Tuesday in October 1996
1064 last DoW in YYYY
1066 The last DoW in the year
1067 last Tuesday in 1997
1068 NOTE: "last DoW" doesn't work in
1070 English since the word "last"
1071 is used for both this expression
1072 and for "prev DoW", which gets
1073 parsed first. "last DoW" MAY
1074 work in other languages.
1075 Nth DoW in MMM [YYYY]
1077 The Nth DoW in the month
1078 3rd Tuesday in October
1079 3rd Tuesday in October 1996
1080 Nth DoW [YYYY]
1082 The Nth DoW in the year
1083 22nd Sunday
1084 22nd Sunday in 1996
1085 DoW week
1087 British: same as "in 1 week on DoW"
1088 Monday week
1089 DoW week N [YYYY]
1091 Dow Nth week [YYYY]
1092 Sunday week 22
1093 Sunday 22nd week
1094 These refer to the day of week
1095 of the Nth week of the year.
1096 Nth
1098 12th
1099 This refers to the Nth day of the
1100 current month.
1101 Note that the formats "Sunday week 22" and "22nd Sunday" give
1103 different behaviors. "Sunday week 22" returns the Sunday of the
1104 22nd week of the year based on how week 1 is defined. ISO 8601
1105 defines week one to contain Jan 4, so "Sunday week 1" might be the
1106 first or second Sunday of the current year, or the last Sunday of
1107 the previous year. "22nd Sunday" gives the actual 22nd time Sunday
1108 occurs in a given year, regardless of the definition of a week.
1109 Special date strings
1111 Most languages have strings which can be used to specify the date
1112 (relative to today). In English, these include the strings:
1113 today
1115 tomorrow
1116 yesterday
1117 There is also support for the British formats:
1119 today week
1121 tomorrow week
1122 yesterday week
1123 which refer to one week after today/tomorrow/yesterday
1125 respectively.
1126 Other languages have similar strings.
1128 In all of the formats (except for ISO 8601 formats), the day of week
1130 ("Friday") can be entered anywhere in the date and it will be checked
1131 for accuracy. In other words,
1132 "Tue Jul 16 1996 13:17:00"
1134 will work but
1136 "Jul 16 1996 Wednesday 13:17:00"
1138 will not (because Jul 16, 1996 is Tuesday, not Wednesday).
1140
1142 There are several categories of time formats supported by Date::Manip.
1143 These are strings which specify only the hour/minute/second fields.
1144 ISO 8601 times
1146 A time may be also be complete or truncated. Again, Date::Manip
1147 treats some formats as complete even though the specification calls
1148 them truncated.
1149 A time may include the following fields:
1151 HH 2-digit representation of the hour
1153 MN 2-digit representation of the minutes
1154 SS 2-digit representation of the seconds
1155 H+ 1+ digit representation of fractional hours
1156 M+ 1+ digit representation of fractional minutes
1157 S+ 1+ digit representation of fractional seconds
1158 The following time formats are considered complete by Date::Manip.
1160 The time 12:30:15 will be expressed in the examples.
1161 Format Notes Examples
1163 HHMNSS 2 123015
1165 HH:MN:SS 12:30:15
1167 HHMNSS,S+ 123015,5
1169 HH:MN:SS,S+ 12:30:15,5
1170 Fractional seconds are ignored
1171 HHMN,M+ 1230,25
1173 HH:MN,M+ 12:30,25
1174 This is 12:30:00 + 0.25 minutes
1175 HH,H+ 12,5
1177 This is 12:00:00 + 0.5 hours, so
1178 this is equivalent to 12:30:00
1179 -MNSS 1 -3015
1181 -MN:SS -30:15
1182 --SS 1 --15
1184 -MNSS,S+ 1 -3015,5
1186 -MN:SS,S+ -30:15,5
1187 -MN,M+ 1 -30,25
1189 --SS,S+ 1 --15,5
1191 HHMN 3 1230
1193 HH:MN 12:30
1194 The following time formats are truncated:
1196 HH 12
1198 -MN -30
1200 Notes:
1202 1 These formats are considered truncated in the standard, but
1204 since
1205 they do include (or imply, using the current time for defaults)
1206 all of
1207 the fields, and since they do not introduce any parsing
1208 complexities,
1209 the standard is relaxed, and they are treated as complete.
1210 2 The HHMNSS format will not be correctly parsed since it is
1212 impossible
1213 to distinguish between it and YYMMDD. In order to parse an all-
1214 digit
1215 time, add the string ",0" to the end to force it to be
1216 interpreted
1217 as a time or include time zone information (either a zone name
1218 or
1219 abbreviation... an offset will not work in this case).
1220 3 The HH:MN format will be treated as complete, even though it is
1222 incomplete due to missing the seconds. In real life, expressing
1223 a time in the HH:MN format is very common, and is regarded as
1224 complete,
1225 and might include time zone information.
1226 ISO 8601 times may be followed by a time zone. Date::Manip relaxes
1228 the constraints placed on the time zone format and allows any of
1229 the methods used to specify the time zone including time zone name,
1230 abbreviation, or offset. The time zone may be separated from the
1231 time by a space, but it is not required.
1232 Another constraint that is relaxed is that the fractional part may
1234 be specified using a period. In other words, the following are
1235 equivalent:
1236 12:30,25
1238 12:30.25
1239 It should be noted (as it is in the specification) that using a
1241 negative time zone offset may cause confusion. In addition to
1242 visually confusing, it may not be parsed correctly. For example,
1243 the time:
1244 123005-0300
1246 may not be parsed correctly. When using an offset time zone, you
1248 should always use the colon separators in the time:
1249 12:30:05-0300
1251 Other time formats
1253 A time may include any of the following fields:
1254 H24 1- or 2-digit representation of the hour (0-23)
1256 H12 1- or 2-digit representation of the hour (1-12)
1257 MN 2-digit representation of the minutes
1258 SS 2-digit representation of the seconds
1259 H+ 1+ digit representation of fractional hours
1260 M+ 1+ digit representation of fractional minutes
1261 S+ 1+ digit representation of fractional seconds
1262 AM A language specific AM/PM string
1263 The following time formats are accepted:
1265 Format Examples
1267 H24:MN:SS 17:30:15
1269 H12:MN:SS AM 5:30:15 PM
1270 H12:MN:SS
1271 H24:MN:SS,S+ 17:30:15,5
1273 H12:MN:SS,S+ AM 5:30:15,5 PM
1274 H12:MN:SS,S+ Fractional seconds are ignored
1275 H24:MN,M+ 17:30,25
1277 H12:MN,M+ AM 5:30,25 PM
1278 H12:MN,M+ This is 17:30:00 + 0.25 minutes
1279 H24,H+ 17,5
1281 H12,H+ AM 5,5 PM
1282 H12,H+ This is 17:00:00 + 0.5 hours, so
1283 this is equivalent to 17:30:00
1284 H24:MN 17:30
1286 H12:MN AM 5:30 PM
1287 H12:MN
1288 H12 AM 5 PM
1290 The fractional part may be specified using a comma, a period, or a
1292 colon. A language specific fractional separator may also be
1293 available for some languages. A colon will only work if the hour,
1294 minute, and second are all explicitly included, but will not work
1295 otherwise.
1296 In other words, the following are equivalent:
1298 12:30:20,25
1300 12:30:20.25
1301 12:30:20:25
1302 Some languages have alternate H:MN and MN:S separators. For
1304 example, one H:MN separator in French is 'h' (the MN:S separator is
1305 still a colon), so the following are equivalent:
1306 12:30:00
1308 12h30:00
1309 Time zone information can be included immediately following the
1311 time. It can be separated by whitespace from the time, or it can
1312 be immediately adjacent.
1313 Special time strings
1315 Different languages may have some words which can be used to
1316 specify a certain time of day. In English, for example, the
1317 following words are equivalent to the time listed:
1318 noon 12:00:00
1320 midnight 00:00:00
1321 So, the following are equivalent:
1323 Jan 2 2009 at noon
1325 Jan 2 2009 12:00:00
1326 There were two possible ways to interpret midnight. One was at the
1328 start of the day (00:00:00) and the other was at the end of the day
1329 (24:00:00 which would actually mean at 00:00:00 of the following
1330 day). The first has been used to maintain backwards compatibility
1331 with Date::Manip 5.xx .
1332 Other languages have similar strings.
1334 In most languages, a word similar to "at" may precede the time (this
1336 does NOT apply to ISO 8601 time formats). This word (which must be
1337 separate from all other parts of the date with whitespace) is optional,
1338 and the following are equivalent:
1339 12:30
1341 at 12:30
1342 The times "12:00 am", "12:00 pm", and "midnight" are not well defined.
1344 Date::Manip uses the following convention:
1345 midnight = 12:00am = 00:00:00
1347 noon = 12:00pm = 12:00:00
1348 and the day goes from 00:00:00 to 23:59:59. In other words, midnight
1350 is the beginning of a day rather than the end of one. The time
1351 24:00:00 is also allowed (though it is automatically transformed to
1352 00:00:00 of the following day). This gives the unusual result of
1353 parsing:
1354 Wed Feb 8 2006 24:00:00
1356 which gives the date of:
1358 Thu Feb 9 2006 00:00:00
1360
1362 There are several categories of strings which specify both the date and
1363 time. These include the following:
1364 ISO 8601 combined date and time
1366 A combined ISO 8601 date and time is a string containing a complete
1367 ISO 8601 date and a complete or truncated ISO 8601 time.
1368 Date::Manip relaxes the restrictions on how the two are combined.
1370 The time may be separated from the date by space, dash, or the
1371 letter T, or the two may be joined with nothing separating them.
1372 When the time immediately follows the date, or when the two are
1374 separated by a dash, the resulting string MUST be unambiguous.
1375 Provided the date includes all of the dashes in it (i.e. YY-MM-DD
1376 instead of YYMMDD), it is rare that there is any ambiguity. If the
1377 date does not include dashes, the strings may be ambiguous, and in
1378 this case, separating the date and time with a space or the letter
1379 T is useful (and perhaps necessary) to correctly interpret the
1380 string.
1381 The DoY formats should always be separated from the time by
1383 something. They are visually confusing if they are not separated
1384 from the time.
1385 Time zone information can be included immediately following a
1387 complete time. It may not be included if no time is given, or if a
1388 truncated time is included. The time zone may be separated from the
1389 time with whitespace, or it can be immediately adjacent to it
1390 (since the ISO 8601 specification allows it in some cases).
1391 Non-ISO 8601 combined date and time
1393 A date from any of the formats above (except for the ISO 8601
1394 formats) may be combined with any of the time formats above (except
1395 for the ISO 8601 time formats) in any combination to form a valid
1396 combined date and time.
1397 Deltas
1399 Dates are often specified in terms of a delta from "now". For
1400 example, "in 2 days".
1401 Any valid delta can be used to specify a date, and the date is
1403 defined as that delta added to "now". Refer to the
1404 Date::Manip::Delta documentation for a list of valid delta formats.
1405 If the delta itself does not include a time part, the time may be
1407 specified explicitly. For example:
1408 in 3 days at 12:00:00
1410 will take the delta part "in 3 days" and add it to the current
1412 time, then set the time to 12:00:00.
1413 It is NOT allowed to include an explicit time if any time segment
1415 was included in the delta. For example, the following is invalid:
1416 in 3 days 2 hours at 12:00:00
1418 One additional format that is supported is to include only week (or
1420 higher) components in the delta and to set the day of week. For
1421 example:
1422 Friday in 2 weeks
1424 in 2 weeks on Friday
1425 Friday 2 weeks ago
1426 2 weeks ago on Friday at 13:45
1427 These first apply the delta (of weeks, months, and years) to the
1429 current time, and then set the day to the given day-of-week in that
1430 week.
1431 Special date and time strings
1433 Most language have strings which can be used to specify the full
1434 date and time (relative to the current date and time). In English,
1435 these include the string:
1436 now
1438 Addition combined date and time formats
1440 The following formats are also supported:
1441 epoch SECS
1443 The number of seconds since the epoch
1444 (Jan 1, 1970 00:00:00 GMT). SECS may
1445 be negative to give time before the
1446 epoch.
1447 A couple of notes:
1449 Commas may be included in all date formats arbitrarily (except for ISO
1451 8601 formats where they may only be included when allowed by the
1452 specification).
1453 The time/time zone is removed from the date before the date is parsed,
1455 so the time may appear before or after the date, or between any two
1456 parts of the date.
1457 Certain words such as "on", "in", "at", "of", etc. which commonly
1459 appear in a date or time are ignored (except in ISO 8601 formats).
1460
1462 The following printf directives are replaced with information from the
1463 date.
1464 Year
1466 %y year - 00 to 99
1467 %Y year - 0001 to 9999
1468 Month, Week
1470 %m month of year - 01 to 12
1471 %f month of year - " 1" to "12"
1472 %b,%h month abbreviation - Jan to Dec
1473 %B month name - January to December
1474 Day
1476 %j day of the year - 001 to 366
1477 %d day of month - 01 to 31
1478 %e day of month - " 1" to "31"
1479 %v weekday abbreviation - " S"," M"," T", ...
1480 %a weekday abbreviation - Sun to Sat
1481 %A weekday name - Sunday to Saturday
1482 %w day of week - 1 to 7 (1=Monday)
1483 %E day of month with
1484 suffix - 1st, 2nd, 3rd...
1485 Hour
1487 %H hour - 00 to 23
1488 %k hour - " 0" to "23"
1489 %i hour - " 1" to "12"
1490 %I hour - 01 to 12
1491 %p AM or PM
1492 Minute, Second, Time zone
1494 %M minute - 00 to 59
1495 %S second - 00 to 59
1496 %Z time zone abbreviation - EDT
1497 %z time zone as GMT offset - +0100 (see Note 4)
1498 %N time zone as GMT offset - +01:00:00
1499 Epoch (see NOTE 3 below)
1501 %s seconds from
1502 1/1/1970 GMT - negative if before
1503 %o seconds from 1/1/1970
1504 in the current time
1505 zone
1506 Date, Time
1508 %c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
1509 %C,%u %a %b %e %H:%M:%S %Z %Y - Fri Apr 28 17:25:57 EDT 1995
1510 %g %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT
1511 %D %m/%d/%y - 04/28/95
1512 %x %m/%d/%y or %d/%m/%y - 04/28/95 or 28/04/28
1513 (Depends on DateFormat variable)
1514 %l date in ls(1) format (see NOTE 1 below)
1515 %b %e %H:%M - Apr 28 17:23 (*)
1516 %b %e %Y - Apr 28 1993 (*)
1517 %r %I:%M:%S %p - 05:39:55 PM
1518 %R %H:%M - 17:40
1519 %T,%X %H:%M:%S - 17:40:58
1520 %V %m%d%H%M%y - 0428174095
1521 %Q %Y%m%d - 19961025
1522 %q %Y%m%d%H%M%S - 19961025174058
1523 %P %Y%m%d%H:%M:%S - 1996102517:40:58
1524 %O %Y-%m-%dT%H:%M:%S - 1996-10-25T17:40:58
1525 %F %A, %B %e, %Y - Sunday, January 1, 1996
1526 %K %Y-%j - 1997-045
1527 Special Year/Week formats (see NOTE 2 below)
1529 %G year, Monday as first
1530 day of week - 0001 to 9999
1531 %W week of year, Monday
1532 as first day of week - 01 to 53
1533 %L year, Sunday as first
1534 day of week - 0001 to 9999
1535 %U week of year, Sunday
1536 as first day of week - 01 to 53
1537 %J %G-W%W-%w - 1997-W02-2
1538 Other formats
1540 %n insert a newline character
1541 %t insert a tab character
1542 %% insert a `%' character
1543 %+ insert a `+' character
1544 All other characters are currently unused, but may be used in the
1546 future. They currently insert the character following the %,
1547 If a lone percent is the final character in a format, it is ignored.
1549 The formats used in this routine were originally based on date.pl
1551 (version 3.2) by Terry McGonigal, as well as a couple taken from
1552 different versions of the Solaris date(1) command. Also, several have
1553 been added which are unique to Date::Manip.
1554 NOTE 1:
1556 The ls format (%l) applies to date within the past OR future 6 months!
1558 Any date that is before the date NOW - 6 months, or that is on or after
1559 the date NOW + 6 months will have the year printed out.
1560 The later time must be on or after so that there is no ambiguity. If it
1562 is now 2000-06-06-12:00:00, then the date 1999-12-06-12:00:00 will be
1563 written as "Dec 6 12:00" but the date 2000-12-06-12:00:00 will be
1564 written as "Dec 6 2000".
1565 NOTE 2:
1567 The %U, %W, %L, %G, and %J formats are used to support the ISO-8601
1569 format: YYYY-wWW-D. In this format, a date is written as a year, the
1570 week of the year, and the day of the week. Technically, the week may
1571 be considered to start on any day of the week, but Sunday and Monday
1572 are the both common choices, so both are supported.
1573 The %W and %G formats return the week-of-year and the year treating
1575 weeks as starting on Monday.
1576 The %U and %L formats return the week-of-year and the year treating
1578 weeks as starting on Sunday.
1579 Most of the time, the %L and %G formats returns the same value as the
1581 %Y format, but there is a problem with days occurring in the first or
1582 last week of the year.
1583 The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D
1585 format is actually 1992-W53-5. In other words, Jan 1 is treated as
1586 being in the last week of the preceding year. Depending on the year,
1587 days in the first week of a year may belong to the previous year, and
1588 days in the final week of a year may belong to the next year. The week
1589 is assigned to the year which has most of the days. For example, if
1590 the week starts on Sunday, then the last week of 2003 is 2003-12-28 to
1591 2004-01-03. This week is assigned to 2003 since 4 of the days in it
1592 are in 2003 and only 3 of them are in 2004. The first week of 2004
1593 starts on 2004-01-04.
1594 The %U and %W formats return a week-of-year number from 01 to 53. %L
1596 and %G return the corresponding year, and to get this type of
1597 information, you should always use the (%W,%G) combination or (%U,%L)
1598 combination. %Y should not be used as it will yield incorrect results.
1599 %J returns the full ISO-8601 format (%G-W%W-%w).
1601 NOTE 3:
1603 The %s and %o formats return negative values if the date is before the
1605 start of the epoch. Other Unix utilities would return an error, or a
1606 zero, so if you are going to use Date::Manip in conjunction with these,
1607 be sure to check for a negative value.
1608 NOTE 4:
1610 The %z format returns the offset in the RFC 822 specified format +0500
1612 . Most offsets are full hour amounts, so this is not a problem, but
1613 some offsets are irregular (+05:17:30). In this case, the string
1614 returned is +051730 which isn't RFC 822 compliant, but since RFC 822
1615 ignores this situation, I had to decide between returning an incorrect
1616 value, or breaking strict compliance, and I chose the second option.
1617
1619 None known.
1620
1622 Please refer to the Date::Manip::Problems documentation for information
1623 on submitting bug reports or questions to the author.
1624
1626 Date::Manip - main module documentation
1627
1629 This script is free software; you can redistribute it and/or modify it
1630 under the same terms as Perl itself.
1631
1633 Sullivan Beck (sbeck@cpan.org)
1634perl v5.12.0 2010-04-27 Date::Manip::Date(3)