1DateTime(3) User Contributed Perl Documentation DateTime(3)
2
6 DateTime - A date and time object
7
9 version 0.70
10
12 use DateTime;
13 $dt = DateTime->new(
15 year => 1964,
16 month => 10,
17 day => 16,
18 hour => 16,
19 minute => 12,
20 second => 47,
21 nanosecond => 500000000,
22 time_zone => 'Asia/Taipei',
23 );
24 $dt = DateTime->from_epoch( epoch => $epoch );
26 $dt = DateTime->now; # same as ( epoch => time() )
27 $year = $dt->year;
29 $month = $dt->month; # 1-12
30 $day = $dt->day; # 1-31
32 $dow = $dt->day_of_week; # 1-7 (Monday is 1)
34 $hour = $dt->hour; # 0-23
36 $minute = $dt->minute; # 0-59
37 $second = $dt->second; # 0-61 (leap seconds!)
39 $doy = $dt->day_of_year; # 1-366 (leap years)
41 $doq = $dt->day_of_quarter; # 1..
43 $qtr = $dt->quarter; # 1-4
45 # all of the start-at-1 methods above have corresponding start-at-0
47 # methods, such as $dt->day_of_month_0, $dt->month_0 and so on
48 $ymd = $dt->ymd; # 2002-12-06
50 $ymd = $dt->ymd('/'); # 2002/12/06
51 $mdy = $dt->mdy; # 12-06-2002
53 $mdy = $dt->mdy('/'); # 12/06/2002
54 $dmy = $dt->dmy; # 06-12-2002
56 $dmy = $dt->dmy('/'); # 06/12/2002
57 $hms = $dt->hms; # 14:02:29
59 $hms = $dt->hms('!'); # 14!02!29
60 $is_leap = $dt->is_leap_year;
62 # these are localizable, see Locales section
64 $month_name = $dt->month_name; # January, February, ...
65 $month_abbr = $dt->month_abbr; # Jan, Feb, ...
66 $day_name = $dt->day_name; # Monday, Tuesday, ...
67 $day_abbr = $dt->day_abbr; # Mon, Tue, ...
68 # May not work for all possible datetime, see the docs on this
70 # method for more details.
71 $epoch_time = $dt->epoch;
72 $dt2 = $dt + $duration_object;
74 $dt3 = $dt - $duration_object;
76 $duration_object = $dt - $dt2;
78 $dt->set( year => 1882 );
80 $dt->set_time_zone( 'America/Chicago' );
82 $dt->set_formatter( $formatter );
84
86 DateTime is a class for the representation of date/time combinations,
87 and is part of the Perl DateTime project. For details on this project
88 please see <http://datetime.perl.org/>. The DateTime site has a FAQ
89 which may help answer many "how do I do X?" questions. The FAQ is at
90 <http://datetime.perl.org/wiki/datetime/page/FAQ>.
91 It represents the Gregorian calendar, extended backwards in time before
93 its creation (in 1582). This is sometimes known as the "proleptic
94 Gregorian calendar". In this calendar, the first day of the calendar
95 (the epoch), is the first day of year 1, which corresponds to the date
96 which was (incorrectly) believed to be the birth of Jesus Christ.
97 The calendar represented does have a year 0, and in that way differs
99 from how dates are often written using "BCE/CE" or "BC/AD".
100 For infinite datetimes, please see the DateTime::Infinite module.
102
104 0-based Versus 1-based Numbers
105 The DateTime.pm module follows a simple consistent logic for
106 determining whether or not a given number is 0-based or 1-based.
107 Month, day of month, day of week, and day of year are 1-based. Any
109 method that is 1-based also has an equivalent 0-based method ending in
110 "_0". So for example, this class provides both "day_of_week()" and
111 "day_of_week_0()" methods.
112 The "day_of_week_0()" method still treats Monday as the first day of
114 the week.
115 All time-related numbers such as hour, minute, and second are 0-based.
117 Years are neither, as they can be both positive or negative, unlike any
119 other datetime component. There is a year 0.
120 There is no "quarter_0()" method.
122 Error Handling
124 Some errors may cause this module to die with an error string. This can
125 only happen when calling constructor methods, methods that change the
126 object, such as "set()", or methods that take parameters. Methods that
127 retrieve information about the object, such as "year()" or "epoch()",
128 will never die.
129 Locales
131 All the object methods which return names or abbreviations return data
132 based on a locale. This is done by setting the locale when constructing
133 a DateTime object. There is also a "DefaultLocale()" class method which
134 may be used to set the default locale for all DateTime objects created.
135 If this is not set, then "en_US" is used.
136 Floating DateTimes
138 The default time zone for new DateTime objects, except where stated
139 otherwise, is the "floating" time zone. This concept comes from the
140 iCal standard. A floating datetime is one which is not anchored to any
141 particular time zone. In addition, floating datetimes do not include
142 leap seconds, since we cannot apply them without knowing the datetime's
143 time zone.
144 The results of date math and comparison between a floating datetime and
146 one with a real time zone are not really valid, because one includes
147 leap seconds and the other does not. Similarly, the results of datetime
148 math between two floating datetimes and two datetimes with time zones
149 are not really comparable.
150 If you are planning to use any objects with a real time zone, it is
152 strongly recommended that you do not mix these with floating datetimes.
153 Math
155 If you are going to be using doing date math, please read the section
156 "How Datetime Math Works".
157 Time Zone Warnings
159 Determining the local time zone for a system can be slow. If $ENV{TZ}
160 is not set, it may involve reading a number of files in /etc or
161 elsewhere. If you know that the local time zone won't change while your
162 code is running, and you need to make many objects for the local time
163 zone, it is strongly recommended that you retrieve the local time zone
164 once and cache it:
165 our $App::LocalTZ = DateTime::TimeZone->new( name => 'local' );
167 ... # then everywhere else
169 my $dt = DateTime->new( ..., time_zone => $App::LocalTZ );
171 DateTime itself does not do this internally because local time zones
173 can change, and there's no good way to determine if it's changed
174 without doing all the work to look it up.
175 Do not try to use named time zones (like "America/Chicago") with dates
177 very far in the future (thousands of years). The current implementation
178 of "DateTime::TimeZone" will use a huge amount of memory calculating
179 all the DST changes from now until the future date. Use UTC or the
180 floating time zone and you will be safe.
181 Methods
183 Constructors
184 All constructors can die when invalid parameters are given.
186 · DateTime->new( ... )
188 This class method accepts parameters for each date and time
190 component: "year", "month", "day", "hour", "minute", "second",
191 "nanosecond". It also accepts "locale", "time_zone", and
192 "formatter" parameters.
193 my $dt = DateTime->new(
195 year => 1966,
196 month => 10,
197 day => 25,
198 hour => 7,
199 minute => 15,
200 second => 47,
201 nanosecond => 500000000,
202 time_zone => 'America/Chicago',
203 );
204 DateTime validates the "month", "day", "hour", "minute", and
206 "second", and "nanosecond" parameters. The valid values for these
207 parameters are:
208 · month
210 An integer from 1-12.
212 · day
214 An integer from 1-31, and it must be within the valid range
216 of days for the specified month.
217 · hour
219 An integer from 0-23.
221 · minute
223 An integer from 0-59.
225 · second
227 An integer from 0-61 (to allow for leap seconds). Values of
229 60 or 61 are only allowed when they match actual leap
230 seconds.
231 · nanosecond
233 An integer >= 0. If this number is greater than 1 billion,
235 it will be normalized into the second value for the
236 DateTime object.
237 Invalid parameter types (like an array reference) will cause the
239 constructor to die.
240 The value for seconds may be from 0 to 61, to account for leap
242 seconds. If you give a value greater than 59, DateTime does check
243 to see that it really matches a valid leap second.
244 All of the parameters are optional except for "year". The "month"
246 and "day" parameters both default to 1, while the "hour", "minute",
247 "second", and "nanosecond" parameters all default to 0.
248 The "locale" parameter should be a string matching one of the valid
250 locales, or a "DateTime::Locale" object. See the DateTime::Locale
251 documentation for details.
252 The time_zone parameter can be either a scalar or a
254 "DateTime::TimeZone" object. A string will simply be passed to the
255 "DateTime::TimeZone->new" method as its "name" parameter. This
256 string may be an Olson DB time zone name ("America/Chicago"), an
257 offset string ("+0630"), or the words "floating" or "local". See
258 the "DateTime::TimeZone" documentation for more details.
259 The default time zone is "floating".
261 The "formatter" can be either a scalar or an object, but the class
263 specified by the scalar or the object must implement a
264 "format_datetime()" method.
265 Parsing Dates
267 This module does not parse dates! That means there is no constructor to
269 which you can pass things like "March 3, 1970 12:34".
270 Instead, take a look at the various "DateTime::Format::*" modules on
272 CPAN. These parse all sorts of different date formats, and you're bound
273 to find something that can handle your particular needs.
274 Ambiguous Local Times
276 Because of Daylight Saving Time, it is possible to specify a local time
278 that is ambiguous. For example, in the US in 2003, the transition from
279 to saving to standard time occurred on October 26, at 02:00:00 local
280 time. The local clock changed from 01:59:59 (saving time) to 01:00:00
281 (standard time). This means that the hour from 01:00:00 through
282 01:59:59 actually occurs twice, though the UTC time continues to move
283 forward.
284 If you specify an ambiguous time, then the latest UTC time is always
286 used, in effect always choosing standard time. In this case, you can
287 simply subtract an hour to the object in order to move to saving time,
288 for example:
289 # This object represent 01:30:00 standard time
291 my $dt = DateTime->new(
292 year => 2003,
293 month => 10,
294 day => 26,
295 hour => 1,
296 minute => 30,
297 second => 0,
298 time_zone => 'America/Chicago',
299 );
300 print $dt->hms; # prints 01:30:00
302 # Now the object represent 01:30:00 saving time
304 $dt->subtract( hours => 1 );
305 print $dt->hms; # still prints 01:30:00
307 Alternately, you could create the object with the UTC time zone, and
309 then call the "set_time_zone()" method to change the time zone. This is
310 a good way to ensure that the time is not ambiguous.
311 Invalid Local Times
313 Another problem introduced by Daylight Saving Time is that certain
315 local times just do not exist. For example, in the US in 2003, the
316 transition from standard to saving time occurred on April 6, at the
317 change to 2:00:00 local time. The local clock changes from 01:59:59
318 (standard time) to 03:00:00 (saving time). This means that there is no
319 02:00:00 through 02:59:59 on April 6!
320 Attempting to create an invalid time currently causes a fatal error.
322 This may change in future version of this module.
323 · DateTime->from_epoch( epoch => $epoch, ... )
325 This class method can be used to construct a new DateTime object
327 from an epoch time instead of components. Just as with the "new()"
328 method, it accepts "time_zone", "locale", and "formatter"
329 parameters.
330 If the epoch value is not an integer, the part after the decimal
332 will be converted to nanoseconds. This is done in order to be
333 compatible with "Time::HiRes". If the floating portion extends past
334 9 decimal places, it will be truncated to nine, so that
335 1.1234567891 will become 1 second and 123,456,789 nanoseconds.
336 By default, the returned object will be in the UTC time zone.
338 · DateTime->now( ... )
340 This class method is equivalent to calling "from_epoch()" with the
342 value returned from Perl's "time()" function. Just as with the
343 "new()" method, it accepts "time_zone" and "locale" parameters.
344 By default, the returned object will be in the UTC time zone.
346 · DateTime->today( ... )
348 This class method is equivalent to:
350 DateTime->now->truncate( to => 'day' );
352 · DateTime->from_object( object => $object, ... )
354 This class method can be used to construct a new DateTime object
356 from any object that implements the "utc_rd_values()" method. All
357 "DateTime::Calendar" modules must implement this method in order to
358 provide cross-calendar compatibility. This method accepts a
359 "locale" and "formatter" parameter
360 If the object passed to this method has a "time_zone()" method,
362 that is used to set the time zone of the newly created
363 "DateTime.pm" object.
364 Otherwise, the returned object will be in the floating time zone.
366 · DateTime->last_day_of_month( ... )
368 This constructor takes the same arguments as can be given to the
370 "new()" method, except for "day". Additionally, both "year" and
371 "month" are required.
372 · DateTime->from_day_of_year( ... )
374 This constructor takes the same arguments as can be given to the
376 "new()" method, except that it does not accept a "month" or "day"
377 argument. Instead, it requires both "year" and "day_of_year". The
378 day of year must be between 1 and 366, and 366 is only allowed for
379 leap years.
380 · $dt->clone()
382 This object method returns a new object that is replica of the
384 object upon which the method is called.
385 "Get" Methods
387 This class has many methods for retrieving information about an object.
389 · $dt->year()
391 Returns the year.
393 · $dt->ce_year()
395 Returns the year according to the BCE/CE numbering system. The year
397 before year 1 in this system is year -1, aka "1 BCE".
398 · $dt->era_name()
400 Returns the long name of the current era, something like "Before
402 Christ". See the Locales section for more details.
403 · $dt->era_abbr()
405 Returns the abbreviated name of the current era, something like
407 "BC". See the Locales section for more details.
408 · $dt->christian_era()
410 Returns a string, either "BC" or "AD", according to the year.
412 · $dt->secular_era()
414 Returns a string, either "BCE" or "CE", according to the year.
416 · $dt->year_with_era()
418 Returns a string containing the year immediately followed by its
420 era abbreviation. The year is the absolute value of "ce_year()", so
421 that year 1 is "1AD" and year 0 is "1BC".
422 · $dt->year_with_christian_era()
424 Like "year_with_era()", but uses the christian_era() to get the era
426 name.
427 · $dt->year_with_secular_era()
429 Like "year_with_era()", but uses the secular_era() method to get
431 the era name.
432 · $dt->month()
434 Returns the month of the year, from 1..12.
436 Also available as "$dt->mon()".
438 · $dt->month_name()
440 Returns the name of the current month. See the Locales section for
442 more details.
443 · $dt->month_abbr()
445 Returns the abbreviated name of the current month. See the Locales
447 section for more details.
448 · $dt->day()
450 Returns the day of the month, from 1..31.
452 Also available as "$dt->mday()" and "$dt->day_of_month()".
454 · $dt->day_of_week()
456 Returns the day of the week as a number, from 1..7, with 1 being
458 Monday and 7 being Sunday.
459 Also available as "$dt->wday()" and "$dt->dow()".
461 · $dt->local_day_of_week()
463 Returns the day of the week as a number, from 1..7. The day
465 corresponding to 1 will vary based on the locale.
466 · $dt->day_name()
468 Returns the name of the current day of the week. See the Locales
470 section for more details.
471 · $dt->day_abbr()
473 Returns the abbreviated name of the current day of the week. See
475 the Locales section for more details.
476 · $dt->day_of_year()
478 Returns the day of the year.
480 Also available as "$dt->doy()".
482 · $dt->quarter()
484 Returns the quarter of the year, from 1..4.
486 · $dt->quarter_name()
488 Returns the name of the current quarter. See the Locales section
490 for more details.
491 · $dt->quarter_abbr()
493 Returns the abbreviated name of the current quarter. See the
495 Locales section for more details.
496 · $dt->day_of_quarter()
498 Returns the day of the quarter.
500 Also available as "$dt->doq()".
502 · $dt->weekday_of_month()
504 Returns a number from 1..5 indicating which week day of the month
506 this is. For example, June 9, 2003 is the second Monday of the
507 month, and so this method returns 2 for that day.
508 · $dt->ymd( $optional_separator )
510 · $dt->mdy( $optional_separator )
512 · $dt->dmy( $optional_separator )
514 Each method returns the year, month, and day, in the order
516 indicated by the method name. Years are zero-padded to four digits.
517 Months and days are 0-padded to two digits.
518 By default, the values are separated by a dash (-), but this can be
520 overridden by passing a value to the method.
521 The "$dt->ymd()" method is also available as "$dt->date()".
523 · $dt->hour()
525 Returns the hour of the day, from 0..23.
527 · $dt->hour_1()
529 Returns the hour of the day, from 1..24.
531 · $dt->hour_12()
533 Returns the hour of the day, from 1..12.
535 · $dt->hour_12_0()
537 Returns the hour of the day, from 0..11.
539 · $dt->am_or_pm()
541 Returns the appropriate localized abbreviation, depending on the
543 current hour.
544 · $dt->minute()
546 Returns the minute of the hour, from 0..59.
548 Also available as "$dt->min()".
550 · $dt->second()
552 Returns the second, from 0..61. The values 60 and 61 are used for
554 leap seconds.
555 Also available as "$dt->sec()".
557 · $dt->fractional_second()
559 Returns the second, as a real number from 0.0 until 61.999999999
561 The values 60 and 61 are used for leap seconds.
563 · $dt->millisecond()
565 Returns the fractional part of the second as milliseconds (1E-3
567 seconds).
568 Half a second is 500 milliseconds.
570 · $dt->microsecond()
572 Returns the fractional part of the second as microseconds (1E-6
574 seconds). This value will be rounded to an integer.
575 Half a second is 500_000 microseconds. This value will be rounded
577 to an integer.
578 · $dt->nanosecond()
580 Returns the fractional part of the second as nanoseconds (1E-9
582 seconds).
583 Half a second is 500_000_000 nanoseconds.
585 · $dt->hms( $optional_separator )
587 Returns the hour, minute, and second, all zero-padded to two
589 digits. If no separator is specified, a colon (:) is used by
590 default.
591 Also available as "$dt->time()".
593 · $dt->datetime()
595 This method is equivalent to:
597 $dt->ymd('-') . 'T' . $dt->hms(':')
599 Also available as "$dt->iso8601()".
601 · $dt->is_leap_year()
603 This method returns a true or false indicating whether or not the
605 datetime object is in a leap year.
606 · $dt->week()
608 ($week_year, $week_number) = $dt->week;
610 Returns information about the calendar week which contains this
612 datetime object. The values returned by this method are also
613 available separately through the week_year and week_number methods.
614 The first week of the year is defined by ISO as the one which
616 contains the fourth day of January, which is equivalent to saying
617 that it's the first week to overlap the new year by at least four
618 days.
619 Typically the week year will be the same as the year that the
621 object is in, but dates at the very beginning of a calendar year
622 often end up in the last week of the prior year, and similarly, the
623 final few days of the year may be placed in the first week of the
624 next year.
625 · $dt->week_year()
627 Returns the year of the week. See "$dt->week()" for details.
629 · $dt->week_number()
631 Returns the week of the year, from 1..53. See "$dt->week()" for
633 details.
634 · $dt->week_of_month()
636 The week of the month, from 0..5. The first week of the month is
638 the first week that contains a Thursday. This is based on the ICU
639 definition of week of month, and correlates to the ISO8601 week of
640 year definition. A day in the week before the week with the first
641 Thursday will be week 0.
642 · $dt->jd()
644 · $dt->mjd()
646 These return the Julian Day and Modified Julian Day, respectively.
648 The value returned is a floating point number. The fractional
649 portion of the number represents the time portion of the datetime.
650 · $dt->time_zone()
652 This returns the "DateTime::TimeZone" object for the datetime
654 object.
655 · $dt->offset()
657 This returns the offset from UTC, in seconds, of the datetime
659 object according to the time zone.
660 · $dt->is_dst()
662 Returns a boolean indicating whether or not the datetime object is
664 currently in Daylight Saving Time or not.
665 · $dt->time_zone_long_name()
667 This is a shortcut for "$dt->time_zone->name". It's provided so
669 that one can use "%{time_zone_long_name}" as a strftime format
670 specifier.
671 · $dt->time_zone_short_name()
673 This method returns the time zone abbreviation for the current time
675 zone, such as "PST" or "GMT". These names are not definitive, and
676 should not be used in any application intended for general use by
677 users around the world.
678 · $dt->strftime( $format, ... )
680 This method implements functionality similar to the "strftime()"
682 method in C. However, if given multiple format strings, then it
683 will return multiple scalars, one for each format string.
684 See the "strftime Patterns" section for a list of all possible
686 strftime patterns.
687 If you give a pattern that doesn't exist, then it is simply treated
689 as text.
690 · $dt->format_cldr( $format, ... )
692 This method implements formatting based on the CLDR date patterns.
694 If given multiple format strings, then it will return multiple
695 scalars, one for each format string.
696 See the "CLDR Patterns" section for a list of all possible CLDR
698 patterns.
699 If you give a pattern that doesn't exist, then it is simply treated
701 as text.
702 · $dt->epoch()
704 Return the UTC epoch value for the datetime object. Internally,
706 this is implemented using "Time::Local", which uses the Unix epoch
707 even on machines with a different epoch (such as MacOS). Datetimes
708 before the start of the epoch will be returned as a negative
709 number.
710 The return value from this method is always an integer.
712 Since the epoch does not account for leap seconds, the epoch time
714 for 1972-12-31T23:59:60 (UTC) is exactly the same as that for
715 1973-01-01T00:00:00.
716 This module uses "Time::Local" to calculate the epoch, which may or
718 may not handle epochs before 1904 or after 2038 (depending on the
719 size of your system's integers, and whether or not Perl was
720 compiled with 64-bit int support).
721 · $dt->hires_epoch()
723 Returns the epoch as a floating point number. The floating point
725 portion of the value represents the nanosecond value of the object.
726 This method is provided for compatibility with the "Time::HiRes"
727 module.
728 · $dt->is_finite()
730 · $dt->is_infinite()
732 These methods allow you to distinguish normal datetime objects from
734 infinite ones. Infinite datetime objects are documented in
735 DateTime::Infinite.
736 · $dt->utc_rd_values()
738 Returns the current UTC Rata Die days, seconds, and nanoseconds as
740 a three element list. This exists primarily to allow other calendar
741 modules to create objects based on the values provided by this
742 object.
743 · $dt->local_rd_values()
745 Returns the current local Rata Die days, seconds, and nanoseconds
747 as a three element list. This exists for the benefit of other
748 modules which might want to use this information for date math,
749 such as "DateTime::Event::Recurrence".
750 · $dt->leap_seconds()
752 Returns the number of leap seconds that have happened up to the
754 datetime represented by the object. For floating datetimes, this
755 always returns 0.
756 · $dt->utc_rd_as_seconds()
758 Returns the current UTC Rata Die days and seconds purely as
760 seconds. This number ignores any fractional seconds stored in the
761 object, as well as leap seconds.
762 · $dt->locale()
764 Returns the current locale object.
766 · $dt->formatter()
768 Returns current formatter object or class. See "Formatters And
770 Stringification" for details.
771 "Set" Methods
773 The remaining methods provided by "DateTime.pm", except where otherwise
775 specified, return the object itself, thus making method chaining
776 possible. For example:
777 my $dt = DateTime->now->set_time_zone( 'Australia/Sydney' );
779 my $first = DateTime
781 ->last_day_of_month( year => 2003, month => 3 )
782 ->add( days => 1 )
783 ->subtract( seconds => 1 );
784 · $dt->set( .. )
786 This method can be used to change the local components of a date
788 time, or its locale. This method accepts any parameter allowed by
789 the "new()" method except for "time_zone". Time zones may be set
790 using the "set_time_zone()" method.
791 This method performs parameters validation just as is done in the
793 "new()" method.
794 · $dt->set_year()
796 · $dt->set_month()
798 · $dt->set_day()
800 · $dt->set_hour()
802 · $dt->set_minute()
804 · $dt->set_second()
806 · $dt->set_nanosecond()
808 · $dt->set_locale()
810 These are shortcuts to calling "set()" with a single key. They all
812 take a single parameter.
813 · $dt->truncate( to => ... )
815 This method allows you to reset some of the local time components
817 in the object to their "zero" values. The "to" parameter is used to
818 specify which values to truncate, and it may be one of "year",
819 "month", "week", "day", "hour", "minute", or "second". For example,
820 if "month" is specified, then the local day becomes 1, and the
821 hour, minute, and second all become 0.
822 If "week" is given, then the datetime is set to the beginning of
824 the week in which it occurs, and the time components are all set to
825 0.
826 · $dt->set_time_zone( $tz )
828 This method accepts either a time zone object or a string that can
830 be passed as the "name" parameter to "DateTime::TimeZone->new()".
831 If the new time zone's offset is different from the old time zone,
832 then the local time is adjusted accordingly.
833 For example:
835 my $dt = DateTime->new(
837 year => 2000,
838 month => 5,
839 day => 10,
840 hour => 15,
841 minute => 15,
842 time_zone => 'America/Los_Angeles',
843 );
844 print $dt->hour; # prints 15
846 $dt->set_time_zone( 'America/Chicago' );
848 print $dt->hour; # prints 17
850 If the old time zone was a floating time zone, then no adjustments
852 to the local time are made, except to account for leap seconds. If
853 the new time zone is floating, then the UTC time is adjusted in
854 order to leave the local time untouched.
855 Fans of Tsai Ming-Liang's films will be happy to know that this
857 does work:
858 my $dt = DateTime->now( time_zone => 'Asia/Taipei' );
860 $dt->set_time_zone( 'Europe/Paris' );
862 Yes, now we can know "ni3 na4 bian1 ji2dian3?"
864 · $dt->set_formatter( $formatter )
866 Set the formatter for the object. See "Formatters And
868 Stringification" for details.
869 You can set this to "undef" to revert to the default formatter.
871 Math Methods
873 Like the set methods, math related methods always return the object
875 itself, to allow for chaining:
876 $dt->add( days => 1 )->subtract( seconds => 1 );
878 · $dt->duration_class()
880 This returns "DateTime::Duration", but exists so that a subclass of
882 "DateTime.pm" can provide a different value.
883 · $dt->add_duration( $duration_object )
885 This method adds a "DateTime::Duration" to the current datetime.
887 See the DateTime::Duration docs for more details.
888 · $dt->add( DateTime::Duration->new parameters )
890 This method is syntactic sugar around the "add_duration()" method.
892 It simply creates a new "DateTime::Duration" object using the
893 parameters given, and then calls the "add_duration()" method.
894 · $dt->subtract_duration( $duration_object )
896 When given a "DateTime::Duration" object, this method simply calls
898 "invert()" on that object and passes that new duration to the
899 "add_duration" method.
900 · $dt->subtract( DateTime::Duration->new parameters )
902 Like "add()", this is syntactic sugar for the "subtract_duration()"
904 method.
905 · $dt->subtract_datetime( $datetime )
907 This method returns a new "DateTime::Duration" object representing
909 the difference between the two dates. The duration is relative to
910 the object from which $datetime is subtracted. For example:
911 2003-03-15 00:00:00.00000000
913 - 2003-02-15 00:00:00.00000000
914 -------------------------------
915 = 1 month
916 Note that this duration is not an absolute measure of the amount of
918 time between the two datetimes, because the length of a month
919 varies, as well as due to the presence of leap seconds.
920 The returned duration may have deltas for months, days, minutes,
922 seconds, and nanoseconds.
923 · $dt->delta_md( $datetime )
925 · $dt->delta_days( $datetime )
927 Each of these methods returns a new "DateTime::Duration" object
929 representing some portion of the difference between two datetimes.
930 The "delta_md()" method returns a duration which contains only the
931 month and day portions of the duration is represented. The
932 "delta_days()" method returns a duration which contains only days.
933 The "delta_md" and "delta_days" methods truncate the duration so
935 that any fractional portion of a day is ignored. Both of these
936 methods operate on the date portion of a datetime only, and so
937 effectively ignore the time zone.
938 Unlike the subtraction methods, these methods always return a
940 positive (or zero) duration.
941 · $dt->delta_ms( $datetime )
943 Returns a duration which contains only minutes and seconds. Any day
945 and month differences to minutes are converted to minutes and
946 seconds. This method also always return a positive (or zero)
947 duration.
948 · $dt->subtract_datetime_absolute( $datetime )
950 This method returns a new "DateTime::Duration" object representing
952 the difference between the two dates in seconds and nanoseconds.
953 This is the only way to accurately measure the absolute amount of
954 time between two datetimes, since units larger than a second do not
955 represent a fixed number of seconds.
956 Class Methods
958 · DateTime->DefaultLocale( $locale )
960 This can be used to specify the default locale to be used when
962 creating DateTime objects. If unset, then "en_US" is used.
963 · DateTime->compare( $dt1, $dt2 )
965 · DateTime->compare_ignore_floating( $dt1, $dt2 )
967 $cmp = DateTime->compare( $dt1, $dt2 );
969 $cmp = DateTime->compare_ignore_floating( $dt1, $dt2 );
971 Compare two DateTime objects. The semantics are compatible with
973 Perl's "sort()" function; it returns -1 if $dt1 < $dt2, 0 if $dt1
974 == $dt2, 1 if $dt1 > $dt2.
975 If one of the two DateTime objects has a floating time zone, it
977 will first be converted to the time zone of the other object. This
978 is what you want most of the time, but it can lead to inconsistent
979 results when you compare a number of DateTime objects, some of
980 which are floating, and some of which are in other time zones.
981 If you want to have consistent results (because you want to sort a
983 number of objects, for example), you can use the
984 "compare_ignore_floating()" method:
985 @dates = sort { DateTime->compare_ignore_floating($a, $b) } @dates;
987 In this case, objects with a floating time zone will be sorted as
989 if they were UTC times.
990 Since DateTime objects overload comparison operators, this:
992 @dates = sort @dates;
994 is equivalent to this:
996 @dates = sort { DateTime->compare($a, $b) } @dates;
998 DateTime objects can be compared to any other calendar class that
1000 implements the "utc_rd_values()" method.
1001 How Datetime Math Works
1003 It's important to have some understanding of how datetime math is
1004 implemented in order to effectively use this module and
1005 "DateTime::Duration".
1006 Making Things Simple
1008 If you want to simplify your life and not have to think too hard about
1010 the nitty-gritty of datetime math, I have several recommendations:
1011 · use the floating time zone
1013 If you do not care about time zones or leap seconds, use the
1015 "floating" timezone:
1016 my $dt = DateTime->now( time_zone => 'floating' );
1018 Math done on two objects in the floating time zone produces very
1020 predictable results.
1021 Note that in most cases you will want to start by creating an
1023 object in a specific zone and then convert it to the floating time
1024 zone. When an object goes from a real zone to the floating zone,
1025 the time for the object remains the same.
1026 This means that passing the floating zone to a constructor may not
1028 do what you want.
1029 my $dt = DateTime->now( time_zone => 'floating' );
1031 is equivalent to
1033 my $dt = DateTime->now( time_zone => 'UTC' )->set_time_zone('floating');
1035 This might not be what you wanted. Instead, you may prefer to do
1037 this:
1038 my $dt = DateTime->now( time_zone => 'local' )->set_time_zone('floating');
1040 · use UTC for all calculations
1042 If you do care about time zones (particularly DST) or leap seconds,
1044 try to use non-UTC time zones for presentation and user input only.
1045 Convert to UTC immediately and convert back to the local time zone
1046 for presentation:
1047 my $dt = DateTime->new( %user_input, time_zone => $user_tz );
1049 $dt->set_time_zone('UTC');
1050 # do various operations - store it, retrieve it, add, subtract, etc.
1052 $dt->set_time_zone($user_tz);
1054 print $dt->datetime;
1055 · math on non-UTC time zones
1057 If you need to do date math on objects with non-UTC time zones,
1059 please read the caveats below carefully. The results "DateTime.pm"
1060 produces are predictable and correct, and mostly intuitive, but
1061 datetime math gets very ugly when time zones are involved, and
1062 there are a few strange corner cases involving subtraction of two
1063 datetimes across a DST change.
1064 If you can always use the floating or UTC time zones, you can skip
1066 ahead to Leap Seconds and Date Math
1067 · date vs datetime math
1069 If you only care about the date (calendar) portion of a datetime,
1071 you should use either "delta_md()" or "delta_days()", not
1072 "subtract_datetime()". This will give predictable, unsurprising
1073 results, free from DST-related complications.
1074 · subtract_datetime() and add_duration()
1076 You must convert your datetime objects to the UTC time zone before
1078 doing date math if you want to make sure that the following
1079 formulas are always true:
1080 $dt2 - $dt1 = $dur
1082 $dt1 + $dur = $dt2
1083 $dt2 - $dur = $dt1
1084 Note that using "delta_days" ensures that this formula always
1086 works, regardless of the timezone of the objects involved, as does
1087 using "subtract_datetime_absolute()". Other methods of subtraction
1088 are not always reversible.
1089 Adding a Duration to a Datetime
1091 The parts of a duration can be broken down into five parts. These are
1093 months, days, minutes, seconds, and nanoseconds. Adding one month to a
1094 date is different than adding 4 weeks or 28, 29, 30, or 31 days.
1095 Similarly, due to DST and leap seconds, adding a day can be different
1096 than adding 86,400 seconds, and adding a minute is not exactly the same
1097 as 60 seconds.
1098 We cannot convert between these units, except for seconds and
1100 nanoseconds, because there is no fixed conversion between the two
1101 units, because of things like leap seconds, DST changes, etc.
1102 "DateTime.pm" always adds (or subtracts) days, then months, minutes,
1104 and then seconds and nanoseconds. If there are any boundary overflows,
1105 these are normalized at each step. For the days and months the local
1106 (not UTC) values are used. For minutes and seconds, the local values
1107 are used. This generally just works.
1108 This means that adding one month and one day to February 28, 2003 will
1110 produce the date April 1, 2003, not March 29, 2003.
1111 my $dt = DateTime->new( year => 2003, month => 2, day => 28 );
1113 $dt->add( months => 1, days => 1 );
1115 # 2003-04-01 - the result
1117 On the other hand, if we add months first, and then separately add
1119 days, we end up with March 29, 2003:
1120 $dt->add( months => 1 )->add( days => 1 );
1122 # 2003-03-29
1124 We see similar strangeness when math crosses a DST boundary:
1126 my $dt = DateTime->new(
1128 year => 2003,
1129 month => 4,
1130 day => 5,
1131 hour => 1,
1132 minute => 58,
1133 time_zone => "America/Chicago",
1134 );
1135 $dt->add( days => 1, minutes => 3 );
1137 # 2003-04-06 02:01:00
1138 $dt->add( minutes => 3 )->add( days => 1 );
1140 # 2003-04-06 03:01:00
1141 Note that if you converted the datetime object to UTC first you would
1143 get predictable results.
1144 If you want to know how many seconds a duration object represents, you
1146 have to add it to a datetime to find out, so you could do:
1147 my $now = DateTime->now( time_zone => 'UTC' );
1149 my $later = $now->clone->add_duration($duration);
1150 my $seconds_dur = $later->subtract_datetime_absolute($now);
1152 This returns a duration which only contains seconds and nanoseconds.
1154 If we were add the duration to a different datetime object we might get
1156 a different number of seconds.
1157 DateTime::Duration supports three different end-of-month algorithms for
1159 adding months. This comes into play when an addition results in a day
1160 past the end of the month (for example, adding one month to January
1161 30).
1162 # 2010-08-31 + 1 month = 2010-10-01
1164 $dt->add( months => 1, end_of_month => 'wrap' );
1165 # 2010-01-30 + 1 month = 2010-02-28
1167 $dt->add( months => 1, end_of_month => 'limit' );
1168 # 2010-04-30 + 1 month = 2010-05-31
1170 $dt->add( months => 1, end_of_month => 'preserve' );
1171 By default, it uses "wrap" for positive durations and "preserve" for
1173 negative durations. See DateTime::Duration for a detailed explanation
1174 of these algorithms.
1175 If you need to do lots of work with durations, take a look at Rick
1177 Measham's "DateTime::Format::Duration" module, which lets you present
1178 information from durations in many useful ways.
1179 There are other subtract/delta methods in DateTime.pm to generate
1181 different types of durations. These methods are "subtract_datetime()",
1182 "subtract_datetime_absolute()", "delta_md()", "delta_days()", and
1183 "delta_ms()".
1184 Datetime Subtraction
1186 Date subtraction is done solely based on the two object's local
1188 datetimes, with one exception to handle DST changes. Also, if the two
1189 datetime objects are in different time zones, one of them is converted
1190 to the other's time zone first before subtraction. This is best
1191 explained through examples:
1192 The first of these probably makes the most sense:
1194 my $dt1 = DateTime->new(
1196 year => 2003,
1197 month => 5,
1198 day => 6,
1199 time_zone => 'America/Chicago',
1200 );
1201 # not DST
1203 my $dt2 = DateTime->new(
1205 year => 2003,
1206 month => 11,
1207 day => 6,
1208 time_zone => 'America/Chicago',
1209 );
1210 # is DST
1212 my $dur = $dt2->subtract_datetime($dt1);
1214 # 6 months
1215 Nice and simple.
1217 This one is a little trickier, but still fairly logical:
1219 my $dt1 = DateTime->new(
1221 year => 2003,
1222 month => 4,
1223 day => 5,
1224 hour => 1,
1225 minute => 58,
1226 time_zone => "America/Chicago",
1227 );
1228 # is DST
1230 my $dt2 = DateTime->new(
1232 year => 2003,
1233 month => 4,
1234 day => 7,
1235 hour => 2,
1236 minute => 1,
1237 time_zone => "America/Chicago",
1238 );
1239 # not DST
1241 my $dur = $dt2->subtract_datetime($dt1);
1243 # 2 days and 3 minutes
1245 Which contradicts the result this one gives, even though they both make
1247 sense:
1248 my $dt1 = DateTime->new(
1250 year => 2003,
1251 month => 4,
1252 day => 5,
1253 hour => 1,
1254 minute => 58,
1255 time_zone => "America/Chicago",
1256 );
1257 # is DST
1259 my $dt2 = DateTime->new(
1261 year => 2003,
1262 month => 4,
1263 day => 6,
1264 hour => 3,
1265 minute => 1,
1266 time_zone => "America/Chicago",
1267 );
1268 # not DST
1270 my $dur = $dt2->subtract_datetime($dt1);
1272 # 1 day and 3 minutes
1274 This last example illustrates the "DST" exception mentioned earlier.
1276 The exception accounts for the fact 2003-04-06 only lasts 23 hours.
1277 And finally:
1279 my $dt2 = DateTime->new(
1281 year => 2003,
1282 month => 10,
1283 day => 26,
1284 hour => 1,
1285 time_zone => 'America/Chicago',
1286 );
1287 my $dt1 = $dt2->clone->subtract( hours => 1 );
1289 my $dur = $dt2->subtract_datetime($dt1);
1291 # 60 minutes
1292 This seems obvious until you realize that subtracting 60 minutes from
1294 $dt2 in the above example still leaves the clock time at "01:00:00".
1295 This time we are accounting for a 25 hour day.
1296 Reversibility
1298 Date math operations are not always reversible. This is because of the
1300 way that addition operations are ordered. As was discussed earlier,
1301 adding 1 day and 3 minutes in one call to "add()" is not the same as
1302 first adding 3 minutes and 1 day in two separate calls.
1303 If we take a duration returned from "subtract_datetime()" and then try
1305 to add or subtract that duration from one of the datetimes we just
1306 used, we sometimes get interesting results:
1307 my $dt1 = DateTime->new(
1309 year => 2003,
1310 month => 4,
1311 day => 5,
1312 hour => 1,
1313 minute => 58,
1314 time_zone => "America/Chicago",
1315 );
1316 my $dt2 = DateTime->new(
1318 year => 2003,
1319 month => 4,
1320 day => 6,
1321 hour => 3,
1322 minute => 1,
1323 time_zone => "America/Chicago",
1324 );
1325 my $dur = $dt2->subtract_datetime($dt1);
1327 # 1 day and 3 minutes
1328 $dt1->add_duration($dur);
1330 # gives us $dt2
1331 $dt2->subtract_duration($dur);
1333 # gives us 2003-04-05 02:58:00 - 1 hour later than $dt1
1334 The "subtract_dauration()" operation gives us a (perhaps) unexpected
1336 answer because it first subtracts one day to get 2003-04-05T03:01:00
1337 and then subtracts 3 minutes to get the final result.
1338 If we explicitly reverse the order we can get the original value of
1340 $dt1. This can be facilitated by "DateTime::Duration"'s
1341 "calendar_duration()" and "clock_duration()" methods:
1342 $dt2->subtract_duration( $dur->clock_duration )
1344 ->subtract_duration( $dur->calendar_duration );
1345 Leap Seconds and Date Math
1347 The presence of leap seconds can cause even more anomalies in date
1349 math. For example, the following is a legal datetime:
1350 my $dt = DateTime->new(
1352 year => 1972,
1353 month => 12,
1354 day => 31,
1355 hour => 23,
1356 minute => 59,
1357 second => 60,
1358 time_zone => 'UTC'
1359 );
1360 If we do the following:
1362 $dt->add( months => 1 );
1364 Then the datetime is now "1973-02-01 00:00:00", because there is no
1366 23:59:60 on 1973-01-31.
1367 Leap seconds also force us to distinguish between minutes and seconds
1369 during date math. Given the following datetime:
1370 my $dt = DateTime->new(
1372 year => 1972,
1373 month => 12,
1374 day => 31,
1375 hour => 23,
1376 minute => 59,
1377 second => 30,
1378 time_zone => 'UTC'
1379 );
1380 we will get different results when adding 1 minute than we get if we
1382 add 60 seconds. This is because in this case, the last minute of the
1383 day, beginning at 23:59:00, actually contains 61 seconds.
1384 Here are the results we get:
1386 # 1972-12-31 23:59:30 - our starting datetime
1388 $dt->clone->add( minutes => 1 );
1390 # 1973-01-01 00:00:30 - one minute later
1391 $dt->clone->add( seconds => 60 );
1393 # 1973-01-01 00:00:29 - 60 seconds later
1394 $dt->clone->add( seconds => 61 );
1396 # 1973-01-01 00:00:30 - 61 seconds later
1397 Local vs. UTC and 24 hours vs. 1 day
1399 When math crosses a daylight saving boundary, a single day may have
1401 more or less than 24 hours.
1402 For example, if you do this:
1404 my $dt = DateTime->new(
1406 year => 2003,
1407 month => 4,
1408 day => 5,
1409 hour => 2,
1410 time_zone => 'America/Chicago',
1411 );
1412 $dt->add( days => 1 );
1414 then you will produce an invalid local time, and therefore an exception
1416 will be thrown.
1417 However, this works:
1419 my $dt = DateTime->new(
1421 year => 2003,
1422 month => 4,
1423 day => 5,
1424 hour => 2,
1425 time_zone => 'America/Chicago',
1426 );
1427 $dt->add( hours => 24 );
1429 and produces a datetime with the local time of "03:00".
1431 If all this makes your head hurt, there is a simple alternative. Just
1433 convert your datetime object to the "UTC" time zone before doing date
1434 math on it, and switch it back to the local time zone afterwards. This
1435 avoids the possibility of having date math throw an exception, and
1436 makes sure that 1 day equals 24 hours. Of course, this may not always
1437 be desirable, so caveat user!
1438 Overloading
1440 This module explicitly overloads the addition (+), subtraction (-),
1441 string and numeric comparison operators. This means that the following
1442 all do sensible things:
1443 my $new_dt = $dt + $duration_obj;
1445 my $new_dt = $dt - $duration_obj;
1447 my $duration_obj = $dt - $new_dt;
1449 foreach my $dt ( sort @dts ) { ... }
1451 Additionally, the fallback parameter is set to true, so other derivable
1453 operators (+=, -=, etc.) will work properly. Do not expect increment
1454 (++) or decrement (--) to do anything useful.
1455 The string comparison operators, "eq" or "ne", will use the string
1457 value to compare with non-DateTime objects.
1458 DateTime objects do not have a numeric value, using "==" or "<=>" to
1460 compare a DateTime object with a non-DateTime object will result in an
1461 exception. To safely sort mixed DateTime and non-DateTime objects, use
1462 "sort { $a cmp $b } @dates".
1463 The module also overloads stringification using the object's formatter,
1465 defaulting to "iso8601()" method. See "Formatters And Stringification"
1466 for details.
1467 Formatters And Stringification
1469 You can optionally specify a "formatter", which is usually a
1470 DateTime::Format::* object/class, to control the stringification of the
1471 DateTime object.
1472 Any of the constructor methods can accept a formatter argument:
1474 my $formatter = DateTime::Format::Strptime->new(...);
1476 my $dt = DateTime->new(year => 2004, formatter => $formatter);
1477 Or, you can set it afterwards:
1479 $dt->set_formatter($formatter);
1481 $formatter = $dt->formatter();
1482 Once you set the formatter, the overloaded stringification method will
1484 use the formatter. If unspecified, the "iso8601()" method is used.
1485 A formatter can be handy when you know that in your application you
1487 want to stringify your DateTime objects into a special format all the
1488 time, for example to a different language.
1489 If you provide a formatter class name or object, it must implement a
1491 "format_datetime" method. This method will be called with just the
1492 DateTime object as its argument.
1493 CLDR Patterns
1495 The CLDR pattern language is both more powerful and more complex than
1496 strftime. Unlike strftime patterns, you often have to explicitly escape
1497 text that you do not want formatted, as the patterns are simply letters
1498 without any prefix.
1499 For example, "yyyy-MM-dd" is a valid CLDR pattern. If you want to
1501 include any lower or upper case ASCII characters as-is, you can
1502 surround them with single quotes ('). If you want to include a single
1503 quote, you must escape it as two single quotes ('').
1504 'Today is ' EEEE
1506 'It is now' h 'o''clock' a
1507 Spaces and any non-letter text will always be passed through as-is.
1509 Many CLDR patterns which produce numbers will pad the number with
1511 leading zeroes depending on the length of the format specifier. For
1512 example, "h" represents the current hour from 1-12. If you specify "hh"
1513 then the 1-9 will have a leading zero prepended.
1514 However, CLDR often uses five of a letter to represent the narrow form
1516 of a pattern. This inconsistency is necessary for backwards
1517 compatibility.
1518 CLDR often distinguishes between the "format" and "stand-alone" forms
1520 of a pattern. The format pattern is used when the thing in question is
1521 being placed into a larger string. The stand-alone form is used when
1522 displaying that item by itself, for example in a calendar.
1523 It also often provides three sizes for each item, wide (the full name),
1525 abbreviated, and narrow. The narrow form is often just a single
1526 character, for example "T" for "Tuesday", and may not be unique.
1527 CLDR provides a fairly complex system for localizing time zones that we
1529 ignore entirely. The time zone patterns just use the information
1530 provided by "DateTime::TimeZone", and do not follow the CLDR spec.
1531 The output of a CLDR pattern is always localized, when applicable.
1533 CLDR provides the following patterns:
1535 · G{1,3}
1537 The abbreviated era (BC, AD).
1539 · GGGG
1541 The wide era (Before Christ, Anno Domini).
1543 · GGGGG
1545 The narrow era, if it exists (and it mostly doesn't).
1547 · y and y{3,}
1549 The year, zero-prefixed as needed. Negative years will start with a
1551 "-", and this will be included in the length calculation.
1552 In other, words the "yyyyy" pattern will format year -1234 as
1554 "-1234", not "-01234".
1555 · yy
1557 This is a special case. It always produces a two-digit year, so
1559 "1976" becomes "76". Negative years will start with a "-", making
1560 them one character longer.
1561 · Y{1,}
1563 The week of the year, from "$dt->week_year()".
1565 · u{1,}
1567 Same as "y" except that "uu" is not a special case.
1569 · Q{1,2}
1571 The quarter as a number (1..4).
1573 · QQQ
1575 The abbreviated format form for the quarter.
1577 · QQQQ
1579 The wide format form for the quarter.
1581 · q{1,2}
1583 The quarter as a number (1..4).
1585 · qqq
1587 The abbreviated stand-alone form for the quarter.
1589 · qqqq
1591 The wide stand-alone form for the quarter.
1593 · M{1,2]
1595 The numerical month.
1597 · MMM
1599 The abbreviated format form for the month.
1601 · MMMM
1603 The wide format form for the month.
1605 · MMMMM
1607 The narrow format form for the month.
1609 · L{1,2]
1611 The numerical month.
1613 · LLL
1615 The abbreviated stand-alone form for the month.
1617 · LLLL
1619 The wide stand-alone form for the month.
1621 · LLLLL
1623 The narrow stand-alone form for the month.
1625 · w{1,2}
1627 The week of the year, from "$dt->week_number()".
1629 · W
1631 The week of the month, from "$dt->week_of_month()".
1633 · d{1,2}
1635 The numeric day of of the month.
1637 · D{1,3}
1639 The numeric day of of the year.
1641 · F
1643 The day of the week in the month, from "$dt->weekday_of_month()".
1645 · g{1,}
1647 The modified Julian day, from "$dt->mjd()".
1649 · E{1,3} and eee
1651 The abbreviated format form for the day of the week.
1653 · EEEE and eeee
1655 The wide format form for the day of the week.
1657 · EEEEE and eeeee
1659 The narrow format form for the day of the week.
1661 · e{1,2}
1663 The local numeric day of the week, from 1 to 7. This number depends
1665 on what day is considered the first day of the week, which varies
1666 by locale. For example, in the US, Sunday is the first day of the
1667 week, so this returns 2 for Monday.
1668 · c
1670 The numeric day of the week from 1 to 7, treating Monday as the
1672 first of the week, regardless of locale.
1673 · ccc
1675 The abbreviated stand-alone form for the day of the week.
1677 · cccc
1679 The wide stand-alone form for the day of the week.
1681 · ccccc
1683 The narrow format form for the day of the week.
1685 · a
1687 The localized form of AM or PM for the time.
1689 · h{1,2}
1691 The hour from 1-12.
1693 · H{1,2}
1695 The hour from 0-23.
1697 · K{1,2}
1699 The hour from 0-11.
1701 · k{1,2}
1703 The hour from 1-24.
1705 · j{1,2}
1707 The hour, in 12 or 24 hour form, based on the preferred form for
1709 the locale. In other words, this is equivalent to either "h{1,2}"
1710 or "H{1,2}".
1711 · m{1,2}
1713 The minute.
1715 · s{1,2}
1717 The second.
1719 · S{1,}
1721 The fractional portion of the seconds, rounded based on the length
1723 of the specifier. This returned without a leading decimal point,
1724 but may have leading or trailing zeroes.
1725 · A{1,}
1727 The millisecond of the day, based on the current time. In other
1729 words, if it is 12:00:00.00, this returns 43200000.
1730 · z{1,3}
1732 The time zone short name.
1734 · zzzz
1736 The time zone long name.
1738 · Z{1,3}
1740 The time zone offset.
1742 · ZZZZ
1744 The time zone short name and the offset as one string, so something
1746 like "CDT-0500".
1747 · v{1,3}
1749 The time zone short name.
1751 · vvvv
1753 The time zone long name.
1755 · V{1,3}
1757 The time zone short name.
1759 · VVVV
1761 The time zone long name.
1763 strftime Patterns
1765 The following patterns are allowed in the format string given to the
1766 "$dt->strftime()" method:
1767 · %a
1769 The abbreviated weekday name.
1771 · %A
1773 The full weekday name.
1775 · %b
1777 The abbreviated month name.
1779 · %B
1781 The full month name.
1783 · %c
1785 The default datetime format for the object's locale.
1787 · %C
1789 The century number (year/100) as a 2-digit integer.
1791 · %d
1793 The day of the month as a decimal number (range 01 to 31).
1795 · %D
1797 Equivalent to %m/%d/%y. This is not a good standard format if you
1799 want folks from both the United States and the rest of the world to
1800 understand the date!
1801 · %e
1803 Like %d, the day of the month as a decimal number, but a leading
1805 zero is replaced by a space.
1806 · %F
1808 Equivalent to %Y-%m-%d (the ISO 8601 date format)
1810 · %G
1812 The ISO 8601 year with century as a decimal number. The 4-digit
1814 year corresponding to the ISO week number (see %V). This has the
1815 same format and value as %Y, except that if the ISO week number
1816 belongs to the previous or next year, that year is used instead.
1817 (TZ)
1818 · %g
1820 Like %G, but without century, i.e., with a 2-digit year (00-99).
1822 · %h
1824 Equivalent to %b.
1826 · %H
1828 The hour as a decimal number using a 24-hour clock (range 00 to
1830 23).
1831 · %I
1833 The hour as a decimal number using a 12-hour clock (range 01 to
1835 12).
1836 · %j
1838 The day of the year as a decimal number (range 001 to 366).
1840 · %k
1842 The hour (24-hour clock) as a decimal number (range 0 to 23);
1844 single digits are preceded by a blank. (See also %H.)
1845 · %l
1847 The hour (12-hour clock) as a decimal number (range 1 to 12);
1849 single digits are preceded by a blank. (See also %I.)
1850 · %m
1852 The month as a decimal number (range 01 to 12).
1854 · %M
1856 The minute as a decimal number (range 00 to 59).
1858 · %n
1860 A newline character.
1862 · %N
1864 The fractional seconds digits. Default is 9 digits (nanoseconds).
1866 %3N milliseconds (3 digits)
1868 %6N microseconds (6 digits)
1869 %9N nanoseconds (9 digits)
1870 · %p
1872 Either `AM' or `PM' according to the given time value, or the
1874 corresponding strings for the current locale. Noon is treated as
1875 `pm' and midnight as `am'.
1876 · %P
1878 Like %p but in lowercase: `am' or `pm' or a corresponding string
1880 for the current locale.
1881 · %r
1883 The time in a.m. or p.m. notation. In the POSIX locale this is
1885 equivalent to `%I:%M:%S %p'.
1886 · %R
1888 The time in 24-hour notation (%H:%M). (SU) For a version including
1890 the seconds, see %T below.
1891 · %s
1893 The number of seconds since the epoch.
1895 · %S
1897 The second as a decimal number (range 00 to 61).
1899 · %t
1901 A tab character.
1903 · %T
1905 The time in 24-hour notation (%H:%M:%S).
1907 · %u
1909 The day of the week as a decimal, range 1 to 7, Monday being 1. See
1911 also %w.
1912 · %U
1914 The week number of the current year as a decimal number, range 00
1916 to 53, starting with the first Sunday as the first day of week 01.
1917 See also %V and %W.
1918 · %V
1920 The ISO 8601:1988 week number of the current year as a decimal
1922 number, range 01 to 53, where week 1 is the first week that has at
1923 least 4 days in the current year, and with Monday as the first day
1924 of the week. See also %U and %W.
1925 · %w
1927 The day of the week as a decimal, range 0 to 6, Sunday being 0. See
1929 also %u.
1930 · %W
1932 The week number of the current year as a decimal number, range 00
1934 to 53, starting with the first Monday as the first day of week 01.
1935 · %x
1937 The default date format for the object's locale.
1939 · %X
1941 The default time format for the object's locale.
1943 · %y
1945 The year as a decimal number without a century (range 00 to 99).
1947 · %Y
1949 The year as a decimal number including the century.
1951 · %z
1953 The time-zone as hour offset from UTC. Required to emit
1955 RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
1956 · %Z
1958 The time zone or name or abbreviation.
1960 · %%
1962 A literal `%' character.
1964 · %{method}
1966 Any method name may be specified using the format "%{method}" name
1968 where "method" is a valid "DateTime.pm" object method.
1969 DateTime.pm and Storable
1971 DateTime implements Storable hooks in order to reduce the size of a
1972 serialized DateTime object.
1973
1975 This module is part of a larger ecosystem of modules in the DateTime
1976 family.
1977 DateTime::Set
1979 The DateTime::Set module represents sets (including recurrences) of
1980 datetimes. Many modules return sets or recurrences.
1981 Format Modules
1983 The various format modules exist to parse and format datetimes. For
1984 example, DateTime::Format::HTTP parses dates according to the RFC 1123
1985 format:
1986 my $datetime
1988 = DateTime::Format::HTTP->parse_datetime('Thu Feb 3 17:03:55 GMT 1994');
1989 print DateTime::Format::HTTP->format_datetime($datetime);
1991 Most format modules are suitable for use as a "formatter" with a
1993 DateTime object.
1994 All format modules start with "DateTime::Format::".
1996 Calendar Modules
1998 There are a number of modules on CPAN that implement non-Gregorian
1999 calendars, such as the Chinese, Mayan, and Julian calendars.
2000 All calendar modules start with "DateTime::Calendar::".
2002 Event Modules
2004 There are a number of modules that calculate the dates for events, such
2005 as Easter, Sunrise, etc.
2006 All event modules start with "DateTime::Event::".
2008 Others
2010 There are many other modules that work with DateTime, including modules
2011 in the "DateTimeX" namespace, as well as others.
2012 See the datetime wiki <http://datetime.perl.org> and search.cpan.org
2014 <http://search.cpan.org/search?query=datetime&mode=dist> for more
2015 details.
2016
2018 The tests in 20infinite.t seem to fail on some machines, particularly
2019 on Win32. This appears to be related to Perl's internal handling of
2020 IEEE infinity and NaN, and seems to be highly platform/compiler/phase
2021 of moon dependent.
2022 If you don't plan to use infinite datetimes you can probably ignore
2024 this. This will be fixed (perhaps) in future versions.
2025
2027 Support for this module is provided via the datetime@perl.org email
2028 list. See http://datetime.perl.org/wiki/datetime/page/Mailing_List for
2029 details.
2030 Please submit bugs to the CPAN RT system at
2032 http://rt.cpan.org/NoAuth/Bugs.html?Dist=DateTime or via email at
2033 bug-datetime@rt.cpan.org.
2034
2036 If you'd like to thank me for the work I've done on this module, please
2037 consider making a "donation" to me via PayPal. I spend a lot of free
2038 time creating free software, and would appreciate any support you'd
2039 care to offer.
2040 Please note that I am not suggesting that you must do this in order for
2042 me to continue working on this particular software. I will continue to
2043 do so, inasmuch as I have in the past, for as long as it interests me.
2044 Similarly, a donation made in this way will probably not make me work
2046 on this software much more, unless I get so many donations that I can
2047 consider working on free software full time, which seems unlikely at
2048 best.
2049 To donate, log into PayPal and send money to autarch@urth.org or use
2051 the button on this page: http://www.urth.org/~autarch/fs-donation.html
2052 <http://www.urth.org/~autarch/fs-donation.html>
2053
2055 datetime@perl.org mailing list
2056 http://datetime.perl.org/
2058
2060 Dave Rolsky <autarch@urth.org>
2061
2063 This software is Copyright (c) 2011 by Dave Rolsky.
2064 This is free software, licensed under:
2066 The Artistic License 2.0 (GPL Compatible)
2068perl v5.12.3 2011-08-30 DateTime(3)