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