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