1DateTime(3) User Contributed Perl Documentation DateTime(3)
2
6 DateTime - A date and time object
7
9 use DateTime;
10 $dt = DateTime->new( year => 1964,
12 month => 10,
13 day => 16,
14 hour => 16,
15 minute => 12,
16 second => 47,
17 nanosecond => 500000000,
18 time_zone => 'Asia/Taipei',
19 );
20 $dt = DateTime->from_epoch( epoch => $epoch );
22 $dt = DateTime->now; # same as ( epoch => time() )
23 $year = $dt->year;
25 $month = $dt->month; # 1-12 - also mon
26 $day = $dt->day; # 1-31 - also day_of_month, mday
28 $dow = $dt->day_of_week; # 1-7 (Monday is 1) - also dow, wday
30 $hour = $dt->hour; # 0-23
32 $minute = $dt->minute; # 0-59 - also min
33 $second = $dt->second; # 0-61 (leap seconds!) - also sec
35 $doy = $dt->day_of_year; # 1-366 (leap years) - also doy
37 $doq = $dt->day_of_quarter; # 1.. - also doq
39 $qtr = $dt->quarter; # 1-4
41 # all of the start-at-1 methods above have correponding start-at-0
43 # methods, such as $dt->day_of_month_0, $dt->month_0 and so on
44 $ymd = $dt->ymd; # 2002-12-06
46 $ymd = $dt->ymd('/'); # 2002/12/06 - also date
47 $mdy = $dt->mdy; # 12-06-2002
49 $mdy = $dt->mdy('/'); # 12/06/2002
50 $dmy = $dt->dmy; # 06-12-2002
52 $dmy = $dt->dmy('/'); # 06/12/2002
53 $hms = $dt->hms; # 14:02:29
55 $hms = $dt->hms('!'); # 14!02!29 - also time
56 $is_leap = $dt->is_leap_year;
58 # these are localizable, see Locales section
60 $month_name = $dt->month_name; # January, February, ...
61 $month_abbr = $dt->month_abbr; # Jan, Feb, ...
62 $day_name = $dt->day_name; # Monday, Tuesday, ...
63 $day_abbr = $dt->day_abbr; # Mon, Tue, ...
64 # May not work for all possible datetime, see the docs on this
66 # method for more details.
67 $epoch_time = $dt->epoch;
68 $dt2 = $dt + $duration_object;
70 $dt3 = $dt - $duration_object;
72 $duration_object = $dt - $dt2;
74 $dt->set( year => 1882 );
76 $dt->set_time_zone( 'America/Chicago' );
78 $dt->set_formatter( $formatter );
80
82 DateTime is a class for the representation of date/time combinations,
83 and is part of the Perl DateTime project. For details on this project
84 please see <http://datetime.perl.org/>. The DateTime site has a FAQ
85 which may help answer many "how do I do X?" questions. The FAQ is at
86 <http://datetime.perl.org/?FAQ>.
87 It represents the Gregorian calendar, extended backwards in time before
89 its creation (in 1582). This is sometimes known as the "proleptic
90 Gregorian calendar". In this calendar, the first day of the calendar
91 (the epoch), is the first day of year 1, which corresponds to the date
92 which was (incorrectly) believed to be the birth of Jesus Christ.
93 The calendar represented does have a year 0, and in that way differs
95 from how dates are often written using "BCE/CE" or "BC/AD".
96 For infinite datetimes, please see the DateTime::Infinite module.
98
100 0-based Versus 1-based Numbers
101 The DateTime.pm module follows a simple consistent logic for
102 determining whether or not a given number is 0-based or 1-based.
103 Month, day of month, day of week, and day of year are 1-based. Any
105 method that is 1-based also has an equivalent 0-based method ending in
106 "_0". So for example, this class provides both "day_of_week()" and
107 "day_of_week_0()" methods.
108 The "day_of_week_0()" method still treats Monday as the first day of
110 the week.
111 All time-related numbers such as hour, minute, and second are 0-based.
113 Years are neither, as they can be both positive or negative, unlike any
115 other datetime component. There is a year 0.
116 There is no "quarter_0()" method.
118 Error Handling
120 Some errors may cause this module to die with an error string. This
121 can only happen when calling constructor methods, methods that change
122 the object, such as "set()", or methods that take parameters. Methods
123 that retrieve information about the object, such as "year()" or
124 "epoch()", will never die.
125 Locales
127 All the object methods which return names or abbreviations return data
128 based on a locale. This is done by setting the locale when
129 constructing a DateTime object. There is also a "DefaultLocale()"
130 class method which may be used to set the default locale for all
131 DateTime objects created. If this is not set, then "en_US" is used.
132 Floating DateTimes
134 The default time zone for new DateTime objects, except where stated
135 otherwise, is the "floating" time zone. This concept comes from the
136 iCal standard. A floating datetime is one which is not anchored to any
137 particular time zone. In addition, floating datetimes do not include
138 leap seconds, since we cannot apply them without knowing the datetime's
139 time zone.
140 The results of date math and comparison between a floating datetime and
142 one with a real time zone are not really valid, because one includes
143 leap seconds and the other does not. Similarly, the results of
144 datetime math between two floating datetimes and two datetimes with
145 time zones are not really comparable.
146 If you are planning to use any objects with a real time zone, it is
148 strongly recommended that you do not mix these with floating datetimes.
149 Math
151 If you are going to be using doing date math, please read the section
152 "How Datetime Math is Done".
153 Time Zone Warnings
155 Determining the local time zone for a system can be slow. If $ENV{TZ}
156 is not set, it may involve reading a number of files in /etc or
157 elsewhere. If you know that the local time zone won't change while your
158 code is running, and you need to make many objects for the local time
159 zone, it is strongly recommended that you retrieve the local time zone
160 once and cache it:
161 our $App::LocalTZ = DateTime::TimeZone->new( name => 'local' );
163 ... # then everywhere else
165 my $dt = DateTime->new( ..., time_zone => $App::LocalTZ );
167 DateTime itself does not do this internally because local time zones
169 can change, and there's no good way to determine if it's changed
170 without doing all the work to look it up.
171 Do not try to use named time zones (like "America/Chicago") with dates
173 very far in the future (thousands of years). The current implementation
174 of "DateTime::TimeZone" will use a huge amount of memory calculating
175 all the DST changes from now until the future date. Use UTC or the
176 floating time zone and you will be safe.
177 Methods
179 Constructors
180 All constructors can die when invalid parameters are given.
182 · DateTime->new( ... )
184 This class method accepts parameters for each date and time
186 component: "year", "month", "day", "hour", "minute", "second",
187 "nanosecond". It also accepts "locale", "time_zone", and
188 "formatter" parameters.
189 my $dt = DateTime->new( year => 1066,
191 month => 10,
192 day => 25,
193 hour => 7,
194 minute => 15,
195 second => 47,
196 nanosecond => 500000000,
197 time_zone => 'America/Chicago',
198 );
199 DateTime validates the "month", "day", "hour", "minute", and
201 "second", and "nanosecond" parameters. The valid values for these
202 parameters are:
203 · month
205 1-12
207 · day
209 1-31, and it must be within the valid range of days for the
211 specified month
212 · hour
214 0-23
216 · minute
218 0-59
220 · second
222 0-61 (to allow for leap seconds). Values of 60 or 61 are
224 only allowed when they match actual leap seconds.
225 · nanosecond
227 >= 0
229 Invalid parameter types (like an array reference) will cause the
231 constructor to die.
232 The value for seconds may be from 0 to 61, to account for leap seconds.
234 If you give a value greater than 59, DateTime does check to see that it
235 really matches a valid leap second.
236 All of the parameters are optional except for "year". The "month" and
238 "day" parameters both default to 1, while the "hour", "minute",
239 "second", and "nanosecond" parameters all default to 0.
240 The "locale" parameter should be a string matching one of the valid
242 locales, or a "DateTime::Locale" object. See the DateTime::Locale
243 documentation for details.
244 The time_zone parameter can be either a scalar or a
246 "DateTime::TimeZone" object. A string will simply be passed to the
247 "DateTime::TimeZone->new" method as its "name" parameter. This string
248 may be an Olson DB time zone name ("America/Chicago"), an offset string
249 ("+0630"), or the words "floating" or "local". See the
250 "DateTime::TimeZone" documentation for more details.
251 The default time zone is "floating".
253 The "formatter" can be either a scalar or an object, but the class
255 specified by the scalar or the object must implement a
256 "format_datetime()" method.
257 Parsing Dates
259 This module does not parse dates! That means there is no constructor to
261 which you can pass things like "March 3, 1970 12:34".
262 Instead, take a look at the various "DateTime::Format::*" modules on
264 CPAN. These parse all sorts of different date formats, and you're bound
265 to find something that can handle your particular needs.
266 Ambiguous Local Times
268 Because of Daylight Saving Time, it is possible to specify a local time
270 that is ambiguous. For example, in the US in 2003, the transition from
271 to saving to standard time occurred on October 26, at 02:00:00 local
272 time. The local clock changed from 01:59:59 (saving time) to 01:00:00
273 (standard time). This means that the hour from 01:00:00 through
274 01:59:59 actually occurs twice, though the UTC time continues to move
275 forward.
276 If you specify an ambiguous time, then the latest UTC time is always
278 used, in effect always choosing standard time. In this case, you can
279 simply subtract an hour to the object in order to move to saving time,
280 for example:
281 # This object represent 01:30:00 standard time
283 my $dt = DateTime->new( year => 2003,
284 month => 10,
285 day => 26,
286 hour => 1,
287 minute => 30,
288 second => 0,
289 time_zone => 'America/Chicago',
290 );
291 print $dt->hms; # prints 01:30:00
293 # Now the object represent 01:30:00 saving time
295 $dt->subtract( hours => 1 );
296 print $dt->hms; # still prints 01:30:00
298 Alternately, you could create the object with the UTC time zone, and
300 then call the "set_time_zone()" method to change the time zone. This
301 is a good way to ensure that the time is not ambiguous.
302 Invalid Local Times
304 Another problem introduced by Daylight Saving Time is that certain
306 local times just do not exist. For example, in the US in 2003, the
307 transition from standard to saving time occurred on April 6, at the
308 change to 2:00:00 local time. The local clock changes from 01:59:59
309 (standard time) to 03:00:00 (saving time). This means that there is no
310 02:00:00 through 02:59:59 on April 6!
311 Attempting to create an invalid time currently causes a fatal error.
313 This may change in future version of this module.
314 · DateTime->from_epoch( epoch => $epoch, ... )
316 This class method can be used to construct a new DateTime object
318 from an epoch time instead of components. Just as with the "new()"
319 method, it accepts "time_zone", "locale", and "formatter"
320 parameters.
321 If the epoch value is not an integer, the part after the decimal
323 will be converted to nanoseconds. This is done in order to be
324 compatible with "Time::HiRes". If the floating portion extends
325 past 9 decimal places, it will be truncated to nine, so that
326 1.1234567891 will become 1 second and 123,456,789 nanoseconds.
327 By default, the returned object will be in the UTC time zone.
329 · DateTime->now( ... )
331 This class method is equivalent to calling "from_epoch()" with the
333 value returned from Perl's "time()" function. Just as with the
334 "new()" method, it accepts "time_zone" and "locale" parameters.
335 By default, the returned object will be in the UTC time zone.
337 · DateTime->today( ... )
339 This class method is equivalent to:
341 DateTime->now->truncate( to => 'day' );
343 · DateTime->from_object( object => $object, ... )
345 This class method can be used to construct a new DateTime object
347 from any object that implements the "utc_rd_values()" method. All
348 "DateTime::Calendar" modules must implement this method in order to
349 provide cross-calendar compatibility. This method accepts a
350 "locale" and "formatter" parameter
351 If the object passed to this method has a "time_zone()" method,
353 that is used to set the time zone of the newly created
354 "DateTime.pm" object.
355 Otherwise, the returned object will be in the floating time zone.
357 · DateTime->last_day_of_month( ... )
359 This constructor takes the same arguments as can be given to the
361 "new()" method, except for "day". Additionally, both "year" and
362 "month" are required.
363 · DateTime->from_day_of_year( ... )
365 This constructor takes the same arguments as can be given to the
367 "new()" method, except that it does not accept a "month" or "day"
368 argument. Instead, it requires both "year" and "day_of_year". The
369 day of year must be between 1 and 366, and 366 is only allowed for
370 leap years.
371 · $dt->clone()
373 This object method returns a new object that is replica of the
375 object upon which the method is called.
376 "Get" Methods
378 This class has many methods for retrieving information about an object.
380 · $dt->year()
382 Returns the year.
384 · $dt->ce_year()
386 Returns the year according to the BCE/CE numbering system. The
388 year before year 1 in this system is year -1, aka "1 BCE".
389 · $dt->era_name()
391 Returns the long name of the current era, something like "Before
393 Christ". See the Locales section for more details.
394 · $dt->era_abbr()
396 Returns the abbreviated name of the current era, something like
398 "BC". See the Locales section for more details.
399 · $dt->christian_era()
401 Returns a string, either "BC" or "AD", according to the year.
403 · $dt->secular_era()
405 Returns a string, either "BCE" or "CE", according to the year.
407 · $dt->year_with_era()
409 Returns a string containing the year immediately followed by its
411 era abbreviation. The year is the absolute value of "ce_year()",
412 so that year 1 is "1AD" and year 0 is "1BC".
413 · $dt->year_with_christian_era()
415 Like "year_with_era()", but uses the christian_era() to get the era
417 name.
418 · $dt->year_with_secular_era()
420 Like "year_with_era()", but uses the secular_era() method to get
422 the era name.
423 · $dt->month()
425 · $dt->mon()
427 Returns the month of the year, from 1..12.
429 · $dt->month_name()
431 Returns the name of the current month. See the Locales section for
433 more details.
434 · $dt->month_abbr()
436 Returns the abbreviated name of the current month. See the Locales
438 section for more details.
439 · $dt->day_of_month()
441 · $dt->day()
443 · $dt->mday()
445 Returns the day of the month, from 1..31.
447 · $dt->day_of_week()
449 · $dt->wday()
451 · $dt->dow()
453 Returns the day of the week as a number, from 1..7, with 1 being
455 Monday and 7 being Sunday.
456 · $dt->local_day_of_week()
458 Returns the day of the week as a number, from 1..7. The day
460 corresponding to 1 will vary based on the locale.
461 · $dt->day_name()
463 Returns the name of the current day of the week. See the Locales
465 section for more details.
466 · $dt->day_abbr()
468 Returns the abbreviated name of the current day of the week. See
470 the Locales section for more details.
471 · $dt->day_of_year()
473 · $dt->doy()
475 Returns the day of the year.
477 · $dt->quarter()
479 Returns the quarter of the year, from 1..4.
481 · $dt->quarter_name()
483 Returns the name of the current quarter. See the Locales section
485 for more details.
486 · $dt->quarter_abbr()
488 Returns the abbreviated name of the current quarter. See the
490 Locales section for more details.
491 · $dt->day_of_quarter()
493 · $dt->doq()
495 Returns the day of the quarter.
497 · $dt->weekday_of_month()
499 Returns a number from 1..5 indicating which week day of the month
501 this is. For example, June 9, 2003 is the second Monday of the
502 month, and so this method returns 2 for that day.
503 · $dt->ymd( $optional_separator ) - also $dt->date(...)
505 · $dt->mdy( $optional_separator )
507 · $dt->dmy( $optional_separator )
509 Each method returns the year, month, and day, in the order
511 indicated by the method name. Years are zero-padded to four
512 digits. Months and days are 0-padded to two digits.
513 By default, the values are separated by a dash (-), but this can be
515 overridden by passing a value to the method.
516 · $dt->hour()
518 Returns the hour of the day, from 0..23.
520 · $dt->hour_1()
522 Returns the hour of the day, from 1..24.
524 · $dt->hour_12()
526 Returns the hour of the day, from 1..12.
528 · $dt->hour_12_0()
530 Returns the hour of the day, from 0..11.
532 · $dt->am_or_pm()
534 Returns the appropriate localized abbreviation, depending on the
536 current hour.
537 · $dt->minute()
539 · $dt->min()
541 Returns the minute of the hour, from 0..59.
543 · $dt->second()
545 · $dt->sec()
547 Returns the second, from 0..61. The values 60 and 61 are used for
549 leap seconds.
550 · $dt->fractional_second()
552 Returns the second, as a real number from 0.0 until 61.999999999
554 The values 60 and 61 are used for leap seconds.
556 · $dt->millisecond()
558 Returns the fractional part of the second as milliseconds (1E-3
560 seconds).
561 Half a second is 500 milliseconds.
563 · $dt->microsecond()
565 Returns the fractional part of the second as microseconds (1E-6
567 seconds). This value will be rounded to an integer.
568 Half a second is 500_000 microseconds. This value will be rounded
570 to an integer.
571 · $dt->nanosecond()
573 Returns the fractional part of the second as nanoseconds (1E-9
575 seconds).
576 Half a second is 500_000_000 nanoseconds.
578 · $dt->hms( $optional_separator )
580 · $dt->time( $optional_separator )
582 Returns the hour, minute, and second, all zero-padded to two
584 digits. If no separator is specified, a colon (:) is used by
585 default.
586 · $dt->datetime()
588 · $dt->iso8601()
590 This method is equivalent to:
592 $dt->ymd('-') . 'T' . $dt->hms(':')
594 · $dt->is_leap_year()
596 This method returns a true or false indicating whether or not the
598 datetime object is in a leap year.
599 · $dt->week()
601 ($week_year, $week_number) = $dt->week;
603 Returns information about the calendar week which contains this
605 datetime object. The values returned by this method are also
606 available separately through the week_year and week_number methods.
607 The first week of the year is defined by ISO as the one which
609 contains the fourth day of January, which is equivalent to saying
610 that it's the first week to overlap the new year by at least four
611 days.
612 Typically the week year will be the same as the year that the
614 object is in, but dates at the very beginning of a calendar year
615 often end up in the last week of the prior year, and similarly, the
616 final few days of the year may be placed in the first week of the
617 next year.
618 · $dt->week_year()
620 Returns the year of the week.
622 · $dt->week_number()
624 Returns the week of the year, from 1..53.
626 · $dt->week_of_month()
628 The week of the month, from 0..5. The first week of the month is
630 the first week that contains a Thursday. This is based on the ICU
631 definition of week of month, and correlates to the ISO8601 week of
632 year definition. A day in the week before the week with the first
633 Thursday will be week 0.
634 · $dt->jd()
636 · $dt->mjd()
638 These return the Julian Day and Modified Julian Day, respectively.
640 The value returned is a floating point number. The fractional
641 portion of the number represents the time portion of the datetime.
642 · $dt->time_zone()
644 This returns the "DateTime::TimeZone" object for the datetime
646 object.
647 · $dt->offset()
649 This returns the offset from UTC, in seconds, of the datetime
651 object according to the time zone.
652 · $dt->is_dst()
654 Returns a boolean indicating whether or not the datetime object is
656 currently in Daylight Saving Time or not.
657 · $dt->time_zone_long_name()
659 This is a shortcut for "$dt->time_zone->name". It's provided so
661 that one can use "%{time_zone_long_name}" as a strftime format
662 specifier.
663 · $dt->time_zone_short_name()
665 This method returns the time zone abbreviation for the current time
667 zone, such as "PST" or "GMT". These names are not definitive, and
668 should not be used in any application intended for general use by
669 users around the world.
670 · $dt->strftime( $format, ... )
672 This method implements functionality similar to the "strftime()"
674 method in C. However, if given multiple format strings, then it
675 will return multiple scalars, one for each format string.
676 See the "strftime Patterns" section for a list of all possible
678 strftime patterns.
679 If you give a pattern that doesn't exist, then it is simply treated
681 as text.
682 · $dt->format_cldr( $format, ... )
684 This method implements formatting based on the CLDR date patterns.
686 If given multiple format strings, then it will return multiple
687 scalars, one for each format string.
688 See the "CLDR Patterns" section for a list of all possible CLDR
690 patterns.
691 If you give a pattern that doesn't exist, then it is simply treated
693 as text.
694 · $dt->epoch()
696 Return the UTC epoch value for the datetime object. Internally,
698 this is implemented using "Time::Local", which uses the Unix epoch
699 even on machines with a different epoch (such as MacOS). Datetimes
700 before the start of the epoch will be returned as a negative
701 number.
702 The return value from this method is always an integer.
704 Since the epoch does not account for leap seconds, the epoch time
706 for 1972-12-31T23:59:60 (UTC) is exactly the same as that for
707 1973-01-01T00:00:00.
708 This module uses "Time::Local" to calculate the epoch, which may or
710 may not handle epochs before 1904 or after 2038 (depending on the
711 size of your system's integers, and whether or not Perl was
712 compiled with 64-bit int support).
713 · $dt->hires_epoch()
715 Returns the epoch as a floating point number. The floating point
717 portion of the value represents the nanosecond value of the object.
718 This method is provided for compatibility with the "Time::HiRes"
719 module.
720 · $dt->is_finite()
722 · $dt->is_infinite
724 These methods allow you to distinguish normal datetime objects from
726 infinite ones. Infinite datetime objects are documented in
727 DateTime::Infinite.
728 · $dt->utc_rd_values()
730 Returns the current UTC Rata Die days, seconds, and nanoseconds as
732 a three element list. This exists primarily to allow other
733 calendar modules to create objects based on the values provided by
734 this object.
735 · $dt->local_rd_values()
737 Returns the current local Rata Die days, seconds, and nanoseconds
739 as a three element list. This exists for the benefit of other
740 modules which might want to use this information for date math,
741 such as "DateTime::Event::Recurrence".
742 · $dt->leap_seconds()
744 Returns the number of leap seconds that have happened up to the
746 datetime represented by the object. For floating datetimes, this
747 always returns 0.
748 · $dt->utc_rd_as_seconds()
750 Returns the current UTC Rata Die days and seconds purely as
752 seconds. This number ignores any fractional seconds stored in the
753 object, as well as leap seconds.
754 · $dt->local_rd_as_seconds() - deprecated
756 Returns the current local Rata Die days and seconds purely as
758 seconds. This number ignores any fractional seconds stored in the
759 object, as well as leap seconds.
760 · $dt->locale()
762 Returns the current locale object.
764 · $dt->formatter()
766 Returns current formatter object or class. See "Formatters And
768 Stringification" for details.
769 "Set" Methods
771 The remaining methods provided by "DateTime.pm", except where otherwise
773 specified, return the object itself, thus making method chaining
774 possible. For example:
775 my $dt = DateTime->now->set_time_zone( 'Australia/Sydney' );
777 my $first = DateTime
779 ->last_day_of_month( year => 2003, month => 3 )
780 ->add( days => 1 )
781 ->subtract( seconds => 1 );
782 · $dt->set( .. )
784 This method can be used to change the local components of a date
786 time, or its locale. This method accepts any parameter allowed by
787 the "new()" method except for "time_zone". Time zones may be set
788 using the "set_time_zone()" method.
789 This method performs parameters validation just as is done in the
791 "new()" method.
792 · $dt->set_year()
794 · $dt->set_month()
796 · $dt->set_day()
798 · $dt->set_hour()
800 · $dt->set_minute()
802 · $dt->set_second()
804 · $dt->set_nanosecond()
806 · $dt->set_locale()
808 These are shortcuts to calling "set()" with a single key. They all
810 take a single parameter.
811 · $dt->truncate( to => ... )
813 This method allows you to reset some of the local time components
815 in the object to their "zero" values. The "to" parameter is used
816 to specify which values to truncate, and it may be one of "year",
817 "month", "week", "day", "hour", "minute", or "second". For
818 example, if "month" is specified, then the local day becomes 1, and
819 the hour, minute, and second all become 0.
820 If "week" is given, then the datetime is set to the beginning of
822 the week in which it occurs, and the time components are all set to
823 0.
824 · $dt->set_time_zone( $tz )
826 This method accepts either a time zone object or a string that can
828 be passed as the "name" parameter to "DateTime::TimeZone->new()".
829 If the new time zone's offset is different from the old time zone,
830 then the local time is adjusted accordingly.
831 For example:
833 my $dt = DateTime->new( year => 2000, month => 5, day => 10,
835 hour => 15, minute => 15,
836 time_zone => 'America/Los_Angeles', );
837 print $dt->hour; # prints 15
839 $dt->set_time_zone( 'America/Chicago' );
841 print $dt->hour; # prints 17
843 If the old time zone was a floating time zone, then no adjustments
845 to the local time are made, except to account for leap seconds. If
846 the new time zone is floating, then the UTC time is adjusted in
847 order to leave the local time untouched.
848 Fans of Tsai Ming-Liang's films will be happy to know that this
850 does work:
851 my $dt = DateTime->now( time_zone => 'Asia/Taipei' );
853 $dt->set_time_zone( 'Europe/Paris' );
855 Yes, now we can know "ni3 na4 bian1 ji2dian3?"
857 · $dt->set_formatter( $formatter )
859 Set the formatter for the object. See "Formatters And
861 Stringification" for details.
862 Math Methods
864 Like the set methods, math related methods always return the object
866 itself, to allow for chaining:
867 $dt->add( days => 1 )->subtract( seconds => 1 );
869 · $dt->duration_class()
871 This returns "DateTime::Duration", but exists so that a subclass of
873 "DateTime.pm" can provide a different value.
874 · $dt->add_duration( $duration_object )
876 This method adds a "DateTime::Duration" to the current datetime.
878 See the DateTime::Duration docs for more details.
879 · $dt->add( DateTime::Duration->new parameters )
881 This method is syntactic sugar around the "add_duration()" method.
883 It simply creates a new "DateTime::Duration" object using the
884 parameters given, and then calls the "add_duration()" method.
885 · $dt->subtract_duration( $duration_object )
887 When given a "DateTime::Duration" object, this method simply calls
889 "invert()" on that object and passes that new duration to the
890 "add_duration" method.
891 · $dt->subtract( DateTime::Duration->new parameters )
893 Like "add()", this is syntactic sugar for the "subtract_duration()"
895 method.
896 · $dt->subtract_datetime( $datetime )
898 This method returns a new "DateTime::Duration" object representing
900 the difference between the two dates. The duration is relative to
901 the object from which $datetime is subtracted. For example:
902 2003-03-15 00:00:00.00000000
904 - 2003-02-15 00:00:00.00000000
905 -------------------------------
907 = 1 month
909 Note that this duration is not an absolute measure of the amount of
911 time between the two datetimes, because the length of a month
912 varies, as well as due to the presence of leap seconds.
913 The returned duration may have deltas for months, days, minutes,
915 seconds, and nanoseconds.
916 · $dt->delta_md( $datetime )
918 · $dt->delta_days( $datetime )
920 Each of these methods returns a new "DateTime::Duration" object
922 representing some portion of the difference between two datetimes.
923 The "delta_md()" method returns a duration which contains only the
924 month and day portions of the duration is represented. The
925 "delta_days()" method returns a duration which contains only days.
926 The "delta_md" and "delta_days" methods truncate the duration so
928 that any fractional portion of a day is ignored. Both of these
929 methods operate on the date portion of a datetime only, and so
930 effectively ignore the time zone.
931 Unlike the subtraction methods, these methods always return a
933 positive (or zero) duration.
934 · $dt->delta_ms( $datetime )
936 Returns a duration which contains only minutes and seconds. Any
938 day and month differences to minutes are converted to minutes and
939 seconds. This method also always return a positive (or zero)
940 duration.
941 · $dt->subtract_datetime_absolute( $datetime )
943 This method returns a new "DateTime::Duration" object representing
945 the difference between the two dates in seconds and nanoseconds.
946 This is the only way to accurately measure the absolute amount of
947 time between two datetimes, since units larger than a second do not
948 represent a fixed number of seconds.
949 Class Methods
951 · DateTime->DefaultLocale( $locale )
953 This can be used to specify the default locale to be used when
955 creating DateTime objects. If unset, then "en_US" is used.
956 · DateTime->compare( $dt1, $dt2 )
958 · DateTime->compare_ignore_floating( $dt1, $dt2 )
960 $cmp = DateTime->compare( $dt1, $dt2 );
962 $cmp = DateTime->compare_ignore_floating( $dt1, $dt2 );
964 Compare two DateTime objects. The semantics are compatible with
966 Perl's "sort()" function; it returns -1 if $dt1 < $dt2, 0 if $dt1
967 == $dt2, 1 if $dt1 > $dt2.
968 If one of the two DateTime objects has a floating time zone, it
970 will first be converted to the time zone of the other object. This
971 is what you want most of the time, but it can lead to inconsistent
972 results when you compare a number of DateTime objects, some of
973 which are floating, and some of which are in other time zones.
974 If you want to have consistent results (because you want to sort a
976 number of objects, for example), you can use the
977 "compare_ignore_floating()" method:
978 @dates = sort { DateTime->compare_ignore_floating($a, $b) } @dates;
980 In this case, objects with a floating time zone will be sorted as
982 if they were UTC times.
983 Since DateTime objects overload comparison operators, this:
985 @dates = sort @dates;
987 is equivalent to this:
989 @dates = sort { DateTime->compare($a, $b) } @dates;
991 DateTime objects can be compared to any other calendar class that
993 implements the "utc_rd_values()" method.
994 How Datetime Math is Done
996 It's important to have some understanding of how datetime math is
997 implemented in order to effectively use this module and
998 "DateTime::Duration".
999 Making Things Simple
1001 If you want to simplify your life and not have to think too hard about
1003 the nitty-gritty of datetime math, I have several recommendations:
1004 · use the floating time zone
1006 If you do not care about time zones or leap seconds, use the
1008 "floating" timezone:
1009 my $dt = DateTime->now( time_zone => 'floating' );
1011 Math done on two objects in the floating time zone produces very
1013 predictable results.
1014 · use UTC for all calculations
1016 If you do care about time zones (particularly DST) or leap seconds,
1018 try to use non-UTC time zones for presentation and user input only.
1019 Convert to UTC immediately and convert back to the local time zone
1020 for presentation:
1021 my $dt = DateTime->new( %user_input, time_zone => $user_tz );
1023 $dt->set_time_zone('UTC');
1024 # do various operations - store it, retrieve it, add, subtract, etc.
1026 $dt->set_time_zone($user_tz);
1028 print $dt->datetime;
1029 · math on non-UTC time zones
1031 If you need to do date math on objects with non-UTC time zones,
1033 please read the caveats below carefully. The results "DateTime.pm"
1034 produces are predictable and correct, and mostly intuitive, but
1035 datetime math gets very ugly when time zones are involved, and
1036 there are a few strange corner cases involving subtraction of two
1037 datetimes across a DST change.
1038 If you can always use the floating or UTC time zones, you can skip
1040 ahead to Leap Seconds and Date Math
1041 · date vs datetime math
1043 If you only care about the date (calendar) portion of a datetime,
1045 you should use either "delta_md()" or "delta_days()", not
1046 "subtract_datetime()". This will give predictable, unsurprising
1047 results, free from DST-related complications.
1048 · subtract_datetime() and add_duration()
1050 You must convert your datetime objects to the UTC time zone before
1052 doing date math if you want to make sure that the following
1053 formulas are always true:
1054 $dt2 - $dt1 = $dur
1056 $dt1 + $dur = $dt2
1057 $dt2 - $dur = $dt1
1058 Note that using "delta_days" ensures that this formula always
1060 works, regardless of the timezone of the objects involved, as does
1061 using "subtract_datetime_absolute()". Other methods of subtraction
1062 are not always reversible.
1063 Adding a Duration to a Datetime
1065 The parts of a duration can be broken down into five parts. These are
1067 months, days, minutes, seconds, and nanoseconds. Adding one month to a
1068 date is different than adding 4 weeks or 28, 29, 30, or 31 days.
1069 Similarly, due to DST and leap seconds, adding a day can be different
1070 than adding 86,400 seconds, and adding a minute is not exactly the same
1071 as 60 seconds.
1072 We cannot convert between these units, except for seconds and
1074 nanoseconds, because there is no fixed conversion between the two
1075 units, because of things like leap seconds, DST changes, etc.
1076 "DateTime.pm" always adds (or subtracts) days, then months, minutes,
1078 and then seconds and nanoseconds. If there are any boundary overflows,
1079 these are normalized at each step. For the days and months the local
1080 (not UTC) values are used. For minutes and seconds, the local values
1081 are used. This generally just works.
1082 This means that adding one month and one day to February 28, 2003 will
1084 produce the date April 1, 2003, not March 29, 2003.
1085 my $dt = DateTime->new( year => 2003, month => 2, day => 28 );
1087 $dt->add( months => 1, days => 1 );
1089 # 2003-04-01 - the result
1091 On the other hand, if we add months first, and then separately add
1093 days, we end up with March 29, 2003:
1094 $dt->add( months => 1 )->add( days => 1 );
1096 # 2003-03-29
1098 We see similar strangeness when math crosses a DST boundary:
1100 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
1102 hour => 1, minute => 58,
1103 time_zone => "America/Chicago",
1104 );
1105 $dt->add( days => 1, minutes => 3 );
1107 # 2003-04-06 02:01:00
1108 $dt->add( minutes => 3 )->add( days => 1 );
1110 # 2003-04-06 03:01:00
1111 Note that if you converted the datetime object to UTC first you would
1113 get predictable results.
1114 If you want to know how many seconds a duration object represents, you
1116 have to add it to a datetime to find out, so you could do:
1117 my $now = DateTime->now( time_zone => 'UTC' );
1119 my $later = $now->clone->add_duration($duration);
1120 my $seconds_dur = $later->subtract_datetime_absolute($now);
1122 This returns a duration which only contains seconds and nanoseconds.
1124 If we were add the duration to a different datetime object we might get
1126 a different number of seconds.
1127 If you need to do lots of work with durations, take a look at Rick
1129 Measham's "DateTime::Format::Duration" module, which lets you present
1130 information from durations in many useful ways.
1131 There are other subtract/delta methods in DateTime.pm to generate
1133 different types of durations. These methods are "subtract_datetime()",
1134 "subtract_datetime_absolute()", "delta_md()", "delta_days()", and
1135 "delta_ms()".
1136 Datetime Subtraction
1138 Date subtraction is done solely based on the two object's local
1140 datetimes, with one exception to handle DST changes. Also, if the two
1141 datetime objects are in different time zones, one of them is converted
1142 to the other's time zone first before subtraction. This is best
1143 explained through examples:
1144 The first of these probably makes the most sense:
1146 my $dt1 = DateTime->new( year => 2003, month => 5, day => 6,
1148 time_zone => 'America/Chicago',
1149 );
1150 # not DST
1151 my $dt2 = DateTime->new( year => 2003, month => 11, day => 6,
1153 time_zone => 'America/Chicago',
1154 );
1155 # is DST
1156 my $dur = $dt2->subtract_datetime($dt1);
1158 # 6 months
1159 Nice and simple.
1161 This one is a little trickier, but still fairly logical:
1163 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1165 hour => 1, minute => 58,
1166 time_zone => "America/Chicago",
1167 );
1168 # is DST
1169 my $dt2 = DateTime->new( year => 2003, month => 4, day => 7,
1171 hour => 2, minute => 1,
1172 time_zone => "America/Chicago",
1173 );
1174 # not DST
1175 my $dur = $dt2->subtract_datetime($dt1);
1177 # 2 days and 3 minutes
1178 Which contradicts the result this one gives, even though they both make
1180 sense:
1181 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1183 hour => 1, minute => 58,
1184 time_zone => "America/Chicago",
1185 );
1186 # is DST
1187 my $dt2 = DateTime->new( year => 2003, month => 4, day => 6,
1189 hour => 3, minute => 1,
1190 time_zone => "America/Chicago",
1191 );
1192 # not DST
1193 my $dur = $dt2->subtract_datetime($dt1);
1195 # 1 day and 3 minutes
1196 This last example illustrates the "DST" exception mentioned earlier.
1198 The exception accounts for the fact 2003-04-06 only lasts 23 hours.
1199 And finally:
1201 my $dt2 = DateTime->new( year => 2003, month => 10, day => 26,
1203 hour => 1,
1204 time_zone => 'America/Chicago',
1205 );
1206 my $dt1 = $dt2->clone->subtract( hours => 1 );
1208 my $dur = $dt2->subtract_datetime($dt1);
1210 # 60 minutes
1211 This seems obvious until you realize that subtracting 60 minutes from
1213 $dt2 in the above example still leaves the clock time at "01:00:00".
1214 This time we are accounting for a 25 hour day.
1215 Reversibility
1217 Date math operations are not always reversible. This is because of the
1219 way that addition operations are ordered. As was discussed earlier,
1220 adding 1 day and 3 minutes in one call to "add()" is not the same as
1221 first adding 3 minutes and 1 day in two separate calls.
1222 If we take a duration returned from "subtract_datetime()" and then try
1224 to add or subtract that duration from one of the datetimes we just
1225 used, we sometimes get interesting results:
1226 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1228 hour => 1, minute => 58,
1229 time_zone => "America/Chicago",
1230 );
1231 my $dt2 = DateTime->new( year => 2003, month => 4, day => 6,
1233 hour => 3, minute => 1,
1234 time_zone => "America/Chicago",
1235 );
1236 my $dur = $dt2->subtract_datetime($dt1);
1238 # 1 day and 3 minutes
1239 $dt1->add_duration($dur);
1241 # gives us $dt2
1242 $dt2->subtract_duration($dur);
1244 # gives us 2003-04-05 02:58:00 - 1 hour later than $dt1
1245 The "subtract_dauration()" operation gives us a (perhaps) unexpected
1247 answer because it first subtracts one day to get 2003-04-05T03:01:00
1248 and then subtracts 3 minutes to get the final result.
1249 If we explicitly reverse the order we can get the original value of
1251 $dt1. This can be facilitated by "DateTime::Duration"'s
1252 "calendar_duration()" and "clock_duration()" methods:
1253 $dt2->subtract_duration( $dur->clock_duration )
1255 ->subtract_duration( $dur->calendar_duration );
1256 Leap Seconds and Date Math
1258 The presence of leap seconds can cause even more anomalies in date
1260 math. For example, the following is a legal datetime:
1261 my $dt = DateTime->new( year => 1972, month => 12, day => 31,
1263 hour => 23, minute => 59, second => 60,
1264 time_zone => 'UTC' );
1265 If we do the following:
1267 $dt->add( months => 1 );
1269 Then the datetime is now "1973-02-01 00:00:00", because there is no
1271 23:59:60 on 1973-01-31.
1272 Leap seconds also force us to distinguish between minutes and seconds
1274 during date math. Given the following datetime:
1275 my $dt = DateTime->new( year => 1972, month => 12, day => 31,
1277 hour => 23, minute => 59, second => 30,
1278 time_zone => 'UTC' );
1279 we will get different results when adding 1 minute than we get if we
1281 add 60 seconds. This is because in this case, the last minute of the
1282 day, beginning at 23:59:00, actually contains 61 seconds.
1283 Here are the results we get:
1285 # 1972-12-31 23:59:30 - our starting datetime
1287 $dt->clone->add( minutes => 1 );
1289 # 1973-01-01 00:00:30 - one minute later
1290 $dt->clone->add( seconds => 60 );
1292 # 1973-01-01 00:00:29 - 60 seconds later
1293 $dt->clone->add( seconds => 61 );
1295 # 1973-01-01 00:00:30 - 61 seconds later
1296 Local vs. UTC and 24 hours vs. 1 day
1298 When math crosses a daylight saving boundary, a single day may have
1300 more or less than 24 hours.
1301 For example, if you do this:
1303 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
1305 hour => 2,
1306 time_zone => 'America/Chicago',
1307 );
1308 $dt->add( days => 1 );
1309 then you will produce an invalid local time, and therefore an exception
1311 will be thrown.
1312 However, this works:
1314 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
1316 hour => 2,
1317 time_zone => 'America/Chicago',
1318 );
1319 $dt->add( hours => 24 );
1320 and produces a datetime with the local time of "03:00".
1322 If all this makes your head hurt, there is a simple alternative. Just
1324 convert your datetime object to the "UTC" time zone before doing date
1325 math on it, and switch it back to the local time zone afterwards. This
1326 avoids the possibility of having date math throw an exception, and
1327 makes sure that 1 day equals 24 hours. Of course, this may not always
1328 be desirable, so caveat user!
1329 Overloading
1331 This module explicitly overloads the addition (+), subtraction (-),
1332 string and numeric comparison operators. This means that the following
1333 all do sensible things:
1334 my $new_dt = $dt + $duration_obj;
1336 my $new_dt = $dt - $duration_obj;
1338 my $duration_obj = $dt - $new_dt;
1340 foreach my $dt ( sort @dts ) { ... }
1342 Additionally, the fallback parameter is set to true, so other derivable
1344 operators (+=, -=, etc.) will work properly. Do not expect increment
1345 (++) or decrement (--) to do anything useful.
1346 If you attempt to sort DateTime objects with non-DateTime.pm objects or
1348 scalars (strings, number, whatever) then an exception will be thrown.
1349 Using the string comparison operators, "eq" or "ne", to compare a
1350 DateTime.pm always returns false.
1351 The module also overloads stringification to use the "iso8601()"
1353 method.
1354 Formatters And Stringification
1356 You can optionally specify a "formatter", which is usually a
1357 DateTime::Format::* object/class, to control the stringification of the
1358 DateTime object.
1359 Any of the constructor methods can accept a formatter argument:
1361 my $formatter = DateTime::Format::Strptime->new(...);
1363 my $dt = DateTime->new(year => 2004, formatter => $formatter);
1364 Or, you can set it afterwards:
1366 $dt->set_formatter($formatter);
1368 $formatter = $dt->formatter();
1369 Once you set the formatter, the overloaded stringification method will
1371 use the formatter. If unspecified, the "iso8601()" method is used.
1372 A formatter can be handy when you know that in your application you
1374 want to stringify your DateTime objects into a special format all the
1375 time, for example to a different language.
1376 If you provide a formatter class name or object, it must implement a
1378 "format_datetime" method. This method will be called with just the
1379 DateTime object as its argument.
1380 strftime Patterns
1382 The following patterns are allowed in the format string given to the
1383 "$dt->strftime()" method:
1384 · %a
1386 The abbreviated weekday name.
1388 · %A
1390 The full weekday name.
1392 · %b
1394 The abbreviated month name.
1396 · %B
1398 The full month name.
1400 · %c
1402 The default datetime format for the object's locale.
1404 · %C
1406 The century number (year/100) as a 2-digit integer.
1408 · %d
1410 The day of the month as a decimal number (range 01 to 31).
1412 · %D
1414 Equivalent to %m/%d/%y. This is not a good standard format if you
1416 want folks from both the United States and the rest of the world to
1417 understand the date!
1418 · %e
1420 Like %d, the day of the month as a decimal number, but a leading
1422 zero is replaced by a space.
1423 · %F
1425 Equivalent to %Y-%m-%d (the ISO 8601 date format)
1427 · %G
1429 The ISO 8601 year with century as a decimal number. The 4-digit
1431 year corresponding to the ISO week number (see %V). This has the
1432 same format and value as %Y, except that if the ISO week number
1433 belongs to the previous or next year, that year is used instead.
1434 (TZ)
1435 · %g
1437 Like %G, but without century, i.e., with a 2-digit year (00-99).
1439 · %h
1441 Equivalent to %b.
1443 · %H
1445 The hour as a decimal number using a 24-hour clock (range 00 to
1447 23).
1448 · %I
1450 The hour as a decimal number using a 12-hour clock (range 01 to
1452 12).
1453 · %j
1455 The day of the year as a decimal number (range 001 to 366).
1457 · %k
1459 The hour (24-hour clock) as a decimal number (range 0 to 23);
1461 single digits are preceded by a blank. (See also %H.)
1462 · %l
1464 The hour (12-hour clock) as a decimal number (range 1 to 12);
1466 single digits are preceded by a blank. (See also %I.)
1467 · %m
1469 The month as a decimal number (range 01 to 12).
1471 · %M
1473 The minute as a decimal number (range 00 to 59).
1475 · %n
1477 A newline character.
1479 · %N
1481 The fractional seconds digits. Default is 9 digits (nanoseconds).
1483 %3N milliseconds (3 digits)
1485 %6N microseconds (6 digits)
1486 %9N nanoseconds (9 digits)
1487 · %p
1489 Either `AM' or `PM' according to the given time value, or the
1491 corresponding strings for the current locale. Noon is treated as
1492 `pm' and midnight as `am'.
1493 · %P
1495 Like %p but in lowercase: `am' or `pm' or a corresponding string
1497 for the current locale.
1498 · %r
1500 The time in a.m. or p.m. notation. In the POSIX locale this is
1502 equivalent to `%I:%M:%S %p'.
1503 · %R
1505 The time in 24-hour notation (%H:%M). (SU) For a version including
1507 the seconds, see %T below.
1508 · %s
1510 The number of seconds since the epoch.
1512 · %S
1514 The second as a decimal number (range 00 to 61).
1516 · %t
1518 A tab character.
1520 · %T
1522 The time in 24-hour notation (%H:%M:%S).
1524 · %u
1526 The day of the week as a decimal, range 1 to 7, Monday being 1.
1528 See also %w.
1529 · %U
1531 The week number of the current year as a decimal number, range 00
1533 to 53, starting with the first Sunday as the first day of week 01.
1534 See also %V and %W.
1535 · %V
1537 The ISO 8601:1988 week number of the current year as a decimal
1539 number, range 01 to 53, where week 1 is the first week that has at
1540 least 4 days in the current year, and with Monday as the first day
1541 of the week. See also %U and %W.
1542 · %w
1544 The day of the week as a decimal, range 0 to 6, Sunday being 0.
1546 See also %u.
1547 · %W
1549 The week number of the current year as a decimal number, range 00
1551 to 53, starting with the first Monday as the first day of week 01.
1552 · %x
1554 The default date format for the object's locale.
1556 · %X
1558 The default time format for the object's locale.
1560 · %y
1562 The year as a decimal number without a century (range 00 to 99).
1564 · %Y
1566 The year as a decimal number including the century.
1568 · %z
1570 The time-zone as hour offset from UTC. Required to emit
1572 RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
1573 · %Z
1575 The time zone or name or abbreviation.
1577 · %%
1579 A literal `%' character.
1581 · %{method}
1583 Any method name may be specified using the format "%{method}" name
1585 where "method" is a valid "DateTime.pm" object method.
1586 CLDR Patterns
1588 The CLDR pattern language is both more powerful and more complex than
1589 strftime. Unlike strftime patterns, you often have to explicitly escape
1590 text that you do not want formatted, as the patterns are simply letters
1591 without any prefix.
1592 For example, "yyyy-MM-dd" is a valid CLDR pattern. If you want to
1594 include any lower or upper case ASCII characters as-is, you can
1595 surround them with single quotes ('). If you want to include a single
1596 quote, you must escape it as two single quotes ('').
1597 'Today is ' EEEE
1599 'It is now' h 'o''clock' a
1600 Spaces and any non-letter text will always be passed through as-is.
1602 Many CLDR patterns which produce numbers will pad the number with
1604 leading zeroes depending on the length of the format specifier. For
1605 example, "h" represents the current hour from 1-12. If you specify "hh"
1606 then the 1-9 will have a leading zero prepended.
1607 However, CLDR often uses five of a letter to represent the narrow form
1609 of a pattern. This inconsistency is necessary for backwards
1610 compatibility.
1611 CLDR often distinguishes between the "format" and "stand-alone" forms
1613 of a pattern. The format pattern is used when the thing in question is
1614 being placed into a larger string. The stand-alone form is used when
1615 displaying that item by itself, for example in a calendar.
1616 It also often provides three sizes for each item, wide (the full name),
1618 abbreviated, and narrow. The narrow form is often just a single
1619 character, for example "T" for "Tuesday", and may not be unique.
1620 CLDR provides a fairly complex system for localizing time zones that we
1622 ignore entirely. The time zone patterns just use the information
1623 provided by "DateTime::TimeZone", and do not follow the CLDR spec.
1624 The output of a CLDR pattern is always localized, when applicable.
1626 CLDR provides the following patterns:
1628 · G{1,3}
1630 The abbreviated era (BC, AD).
1632 · GGGG
1634 The wide era (Before Christ, Anno Domini).
1636 · GGGGG
1638 The narrow era, if it exists (and it mostly doesn't).
1640 · y and y{3,}
1642 The year, zero-prefixed as needed. Negative years will start with a
1644 "-", and this will be included in the length calculation.
1645 In other, words the "yyyyy" pattern will format year -1234 as
1647 "-1234", not "-01234".
1648 · yy
1650 This is a special case. It always produces a two-digit year, so
1652 "1976" becomes "76". Negative years will start with a "-", making
1653 them one character longer.
1654 · Y{1,}
1656 The week of the year, from "$dt->week_year()".
1658 · u{1,}
1660 Same as "y" except that "uu" is not a special case.
1662 · Q{1,2}
1664 The quarter as a number (1..4).
1666 · QQQ
1668 The abbreviated format form for the quarter.
1670 · QQQQ
1672 The wide format form for the quarter.
1674 · q{1,2}
1676 The quarter as a number (1..4).
1678 · qqq
1680 The abbreviated stand-alone form for the quarter.
1682 · qqqq
1684 The wide stand-alone form for the quarter.
1686 · M{1,2]
1688 The numerical month.
1690 · MMM
1692 The abbreviated format form for the month.
1694 · MMMM
1696 The wide format form for the month.
1698 · MMMMM
1700 The narrow format form for the month.
1702 · L{1,2]
1704 The numerical month.
1706 · LLL
1708 The abbreviated stand-alone form for the month.
1710 · LLLL
1712 The wide stand-alone form for the month.
1714 · LLLLL
1716 The narrow stand-alone form for the month.
1718 · w{1,2}
1720 The week of the year, from "$dt->week_number()".
1722 · W
1724 The week of the month, from "$dt->week_of_month()".
1726 · d{1,2}
1728 The numeric day of of the month.
1730 · D{1,3}
1732 The numeric day of of the year.
1734 · F
1736 The day of the week in the month, from "$dt->weekday_of_month()".
1738 · g{1,}
1740 The modified Julian day, from "$dt->mjd()".
1742 · E{1,3} and eee
1744 The abbreviated format form for the day of the week.
1746 · EEEE and eeee
1748 The wide format form for the day of the week.
1750 · EEEEE and eeeee
1752 The narrow format form for the day of the week.
1754 · e{1,2}
1756 The local numeric day of the week, from 1 to 7. This number depends
1758 on what day is considered the first day of the week, which varies
1759 by locale. For example, in the US, Sunday is the first day of the
1760 week, so this returns 2 for Monday.
1761 · c
1763 The numeric day of the week from 1 to 7, treating Monday as the
1765 first of the week, regardless of locale.
1766 · ccc
1768 The abbreviated stand-alone form for the day of the week.
1770 · cccc
1772 The wide stand-alone form for the day of the week.
1774 · ccccc
1776 The narrow format form for the day of the week.
1778 · a
1780 The localized form of AM or PM for the time.
1782 · h{1,2}
1784 The hour from 1-12.
1786 · H{1,2}
1788 The hour from 0-23.
1790 · K{1,2}
1792 The hour from 0-11.
1794 · k{1,2}
1796 The hour from 1-24.
1798 · j{1,2}
1800 The hour, in 12 or 24 hour form, based on the preferred form for
1802 the locale. In other words, this is equivalent to either "h{1,2}"
1803 or "H{1,2}".
1804 · m{1,2}
1806 The minute.
1808 · s{1,2}
1810 The second.
1812 · S{1,}
1814 The fractional portion of the seconds, rounded based on the length
1816 of the specifier. This returned without a leading decimal point,
1817 but may have leading or trailing zeroes.
1818 · A{1,}
1820 The millisecond of the day, based on the current time. In other
1822 words, if it is 12:00:00.00, this returns 43200000.
1823 · z{1,3}
1825 The time zone short name.
1827 · zzzz
1829 The time zone long name.
1831 · Z{1,3}
1833 The time zone short name and the offset as one string, so something
1835 like "CDT-0500".
1836 · ZZZZ
1838 The time zone long name.
1840 · v{1,3}
1842 The time zone short name.
1844 · vvvv
1846 The time zone long name.
1848 · V{1,3}
1850 The time zone short name.
1852 · VVVV
1854 The time zone long name.
1856
1858 DateTime implements Storable hooks in order to reduce the size of a
1859 serialized DateTime object.
1860
1862 The tests in 20infinite.t seem to fail on some machines, particularly
1863 on Win32. This appears to be related to Perl's internal handling of
1864 IEEE infinity and NaN, and seems to be highly platform/compiler/phase
1865 of moon dependent.
1866 If you don't plan to use infinite datetimes you can probably ignore
1868 this. This will be fixed (somehow) in future versions.
1869
1871 Support for this module is provided via the datetime@perl.org email
1872 list. See http://datetime.perl.org/?MailingList for details.
1873 Please submit bugs to the CPAN RT system at
1875 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime or via email at
1876 bug-datetime@rt.cpan.org.
1877
1879 If you'd like to thank me for the work I've done on this module, please
1880 consider making a "donation" to me via PayPal. I spend a lot of free
1881 time creating free software, and would appreciate any support you'd
1882 care to offer.
1883 Please note that I am not suggesting that you must do this in order for
1885 me to continue working on this particular software. I will continue to
1886 do so, inasmuch as I have in the past, for as long as it interests me.
1887 Similarly, a donation made in this way will probably not make me work
1889 on this software much more, unless I get so many donations that I can
1890 consider working on free software full time, which seems unlikely at
1891 best.
1892 To donate, log into PayPal and send money to autarch@urth.org or use
1894 the button on this page:
1895 <http://www.urth.org/~autarch/fs-donation.html>
1896
1898 Dave Rolsky <autarch@urth.org>
1899 However, please see the CREDITS file for more details on who I really
1901 stole all the code from.
1902
1904 Copyright (c) 2003-2009 David Rolsky. All rights reserved. This
1905 program is free software; you can redistribute it and/or modify it
1906 under the same terms as Perl itself.
1907 Portions of the code in this distribution are derived from other works.
1909 Please see the CREDITS file for more details.
1910 The full text of the license can be found in the LICENSE file included
1912 with this module.
1913
1915 datetime@perl.org mailing list
1916 http://datetime.perl.org/
1918perl v5.10.1 2017-03-21 DateTime(3)