1NAME
2 DateTime - A date and time object
3
4SYNOPSIS
5 use DateTime;
6
7 $dt = DateTime->new( year => 1964,
8 month => 10,
9 day => 16,
10 hour => 16,
11 minute => 12,
12 second => 47,
13 nanosecond => 500000000,
14 time_zone => 'Asia/Taipei',
15 );
16
17 $dt = DateTime->from_epoch( epoch => $epoch );
18 $dt = DateTime->now; # same as ( epoch => time() )
19
20 $year = $dt->year;
21 $month = $dt->month; # 1-12 - also mon
22
23 $day = $dt->day; # 1-31 - also day_of_month, mday
24
25 $dow = $dt->day_of_week; # 1-7 (Monday is 1) - also dow, wday
26
27 $hour = $dt->hour; # 0-23
28 $minute = $dt->minute; # 0-59 - also min
29
30 $second = $dt->second; # 0-61 (leap seconds!) - also sec
31
32 $doy = $dt->day_of_year; # 1-366 (leap years) - also doy
33
34 $doq = $dt->day_of_quarter; # 1.. - also doq
35
36 $qtr = $dt->quarter; # 1-4
37
38 # all of the start-at-1 methods above have correponding start-at-0
39 # methods, such as $dt->day_of_month_0, $dt->month_0 and so on
40
41 $ymd = $dt->ymd; # 2002-12-06
42 $ymd = $dt->ymd('/'); # 2002/12/06 - also date
43
44 $mdy = $dt->mdy; # 12-06-2002
45 $mdy = $dt->mdy('/'); # 12/06/2002
46
47 $dmy = $dt->dmy; # 06-12-2002
48 $dmy = $dt->dmy('/'); # 06/12/2002
49
50 $hms = $dt->hms; # 14:02:29
51 $hms = $dt->hms('!'); # 14!02!29 - also time
52
53 $is_leap = $dt->is_leap_year;
54
55 # these are localizable, see Locales section
56 $month_name = $dt->month_name; # January, February, ...
57 $month_abbr = $dt->month_abbr; # Jan, Feb, ...
58 $day_name = $dt->day_name; # Monday, Tuesday, ...
59 $day_abbr = $dt->day_abbr; # Mon, Tue, ...
60
61 # May not work for all possible datetime, see the docs on this
62 # method for more details.
63 $epoch_time = $dt->epoch;
64
65 $dt2 = $dt + $duration_object;
66
67 $dt3 = $dt - $duration_object;
68
69 $duration_object = $dt - $dt2;
70
71 $dt->set( year => 1882 );
72
73 $dt->set_time_zone( 'America/Chicago' );
74
75 $dt->set_formatter( $formatter );
76
77DESCRIPTION
78 DateTime is a class for the representation of date/time combinations,
79 and is part of the Perl DateTime project. For details on this project
80 please see http://datetime.perl.org/. The DateTime site has a FAQ which
81 may help answer many "how do I do X?" questions. The FAQ is at
82 http://datetime.perl.org/?FAQ.
83
84 It represents the Gregorian calendar, extended backwards in time before
85 its creation (in 1582). This is sometimes known as the "proleptic
86 Gregorian calendar". In this calendar, the first day of the calendar
87 (the epoch), is the first day of year 1, which corresponds to the date
88 which was (incorrectly) believed to be the birth of Jesus Christ.
89
90 The calendar represented does have a year 0, and in that way differs
91 from how dates are often written using "BCE/CE" or "BC/AD".
92
93 For infinite datetimes, please see the DateTime::Infinite module.
94
95USAGE
96 0-based Versus 1-based Numbers
97 The DateTime.pm module follows a simple consistent logic for determining
98 whether or not a given number is 0-based or 1-based.
99
100 Month, day of month, day of week, and day of year are 1-based. Any
101 method that is 1-based also has an equivalent 0-based method ending in
102 "_0". So for example, this class provides both `day_of_week()' and
103 `day_of_week_0()' methods.
104
105 The `day_of_week_0()' method still treats Monday as the first day of the
106 week.
107
108 All *time*-related numbers such as hour, minute, and second are 0-based.
109
110 Years are neither, as they can be both positive or negative, unlike any
111 other datetime component. There *is* a year 0.
112
113 There is no `quarter_0()' method.
114
115 Error Handling
116 Some errors may cause this module to die with an error string. This can
117 only happen when calling constructor methods, methods that change the
118 object, such as `set()', or methods that take parameters. Methods that
119 retrieve information about the object, such as `year()' or `epoch()',
120 will never die.
121
122 Locales
123 All the object methods which return names or abbreviations return data
124 based on a locale. This is done by setting the locale when constructing
125 a DateTime object. There is also a `DefaultLocale()' class method which
126 may be used to set the default locale for all DateTime objects created.
127 If this is not set, then "en_US" is used.
128
129 Floating DateTimes
130 The default time zone for new DateTime objects, except where stated
131 otherwise, is the "floating" time zone. This concept comes from the iCal
132 standard. A floating datetime is one which is not anchored to any
133 particular time zone. In addition, floating datetimes do not include
134 leap seconds, since we cannot apply them without knowing the datetime's
135 time zone.
136
137 The results of date math and comparison between a floating datetime and
138 one with a real time zone are not really valid, because one includes
139 leap seconds and the other does not. Similarly, the results of datetime
140 math between two floating datetimes and two datetimes with time zones
141 are not really comparable.
142
143 If you are planning to use any objects with a real time zone, it is
144 strongly recommended that you do not mix these with floating datetimes.
145
146 Math
147 If you are going to be using doing date math, please read the section
148 How Datetime Math is Done.
149
150 Time Zone Warnings
151 Determining the local time zone for a system can be slow. If `$ENV{TZ}'
152 is not set, it may involve reading a number of files in /etc or
153 elsewhere. If you know that the local time zone won't change while your
154 code is running, and you need to make many objects for the local time
155 zone, it is strongly recommended that you retrieve the local time zone
156 once and cache it:
157
158 our $App::LocalTZ = DateTime::TimeZone->new( name => 'local' );
159
160 ... # then everywhere else
161
162 my $dt = DateTime->new( ..., time_zone => $App::LocalTZ );
163
164 DateTime itself does not do this internally because local time zones can
165 change, and there's no good way to determine if it's changed without
166 doing all the work to look it up.
167
168 Do not try to use named time zones (like "America/Chicago") with dates
169 very far in the future (thousands of years). The current implementation
170 of `DateTime::TimeZone' will use a huge amount of memory calculating all
171 the DST changes from now until the future date. Use UTC or the floating
172 time zone and you will be safe.
173
174 Methods
175 Constructors
176 All constructors can die when invalid parameters are given.
177
178 * DateTime->new( ... )
179 This class method accepts parameters for each date and time
180 component: "year", "month", "day", "hour", "minute", "second",
181 "nanosecond". It also accepts "locale", "time_zone", and "formatter"
182 parameters.
183
184 my $dt = DateTime->new( year => 1066,
185 month => 10,
186 day => 25,
187 hour => 7,
188 minute => 15,
189 second => 47,
190 nanosecond => 500000000,
191 time_zone => 'America/Chicago',
192 );
193
194 DateTime validates the "month", "day", "hour", "minute", and
195 "second", and "nanosecond" parameters. The valid values for these
196 parameters are:
197
198 * month 1-12
199
200 * day 1-31, and it must be within the valid range of days for the
201 specified month
202
203 * hour 0-23
204
205 * minute
206 0-59
207
208 * second
209 0-61 (to allow for leap seconds). Values of 60 or 61 are
210 only allowed when they match actual leap seconds.
211
212 * nanosecond
213 >= 0
214
215 Invalid parameter types (like an array reference) will cause the
216 constructor to die.
217
218 The value for seconds may be from 0 to 61, to account for leap seconds.
219 If you give a value greater than 59, DateTime does check to see that it
220 really matches a valid leap second.
221
222 All of the parameters are optional except for "year". The "month" and
223 "day" parameters both default to 1, while the "hour", "minute",
224 "second", and "nanosecond" parameters all default to 0.
225
226 The "locale" parameter should be a string matching one of the valid
227 locales, or a `DateTime::Locale' object. See the DateTime::Locale
228 documentation for details.
229
230 The time_zone parameter can be either a scalar or a `DateTime::TimeZone'
231 object. A string will simply be passed to the `DateTime::TimeZone->new'
232 method as its "name" parameter. This string may be an Olson DB time zone
233 name ("America/Chicago"), an offset string ("+0630"), or the words
234 "floating" or "local". See the `DateTime::TimeZone' documentation for
235 more details.
236
237 The default time zone is "floating".
238
239 The "formatter" can be either a scalar or an object, but the class
240 specified by the scalar or the object must implement a
241 `format_datetime()' method.
242
243 Parsing Dates
244 This module does not parse dates! That means there is no constructor to
245 which you can pass things like "March 3, 1970 12:34".
246
247 Instead, take a look at the various `DateTime::Format::*' modules on
248 CPAN. These parse all sorts of different date formats, and you're bound
249 to find something that can handle your particular needs.
250
251 Ambiguous Local Times
252 Because of Daylight Saving Time, it is possible to specify a local time
253 that is ambiguous. For example, in the US in 2003, the transition from
254 to saving to standard time occurred on October 26, at 02:00:00 local
255 time. The local clock changed from 01:59:59 (saving time) to 01:00:00
256 (standard time). This means that the hour from 01:00:00 through 01:59:59
257 actually occurs twice, though the UTC time continues to move forward.
258
259 If you specify an ambiguous time, then the latest UTC time is always
260 used, in effect always choosing standard time. In this case, you can
261 simply subtract an hour to the object in order to move to saving time,
262 for example:
263
264 # This object represent 01:30:00 standard time
265 my $dt = DateTime->new( year => 2003,
266 month => 10,
267 day => 26,
268 hour => 1,
269 minute => 30,
270 second => 0,
271 time_zone => 'America/Chicago',
272 );
273
274 print $dt->hms; # prints 01:30:00
275
276 # Now the object represent 01:30:00 saving time
277 $dt->subtract( hours => 1 );
278
279 print $dt->hms; # still prints 01:30:00
280
281 Alternately, you could create the object with the UTC time zone, and
282 then call the `set_time_zone()' method to change the time zone. This is
283 a good way to ensure that the time is not ambiguous.
284
285 Invalid Local Times
286 Another problem introduced by Daylight Saving Time is that certain local
287 times just do not exist. For example, in the US in 2003, the transition
288 from standard to saving time occurred on April 6, at the change to
289 2:00:00 local time. The local clock changes from 01:59:59 (standard
290 time) to 03:00:00 (saving time). This means that there is no 02:00:00
291 through 02:59:59 on April 6!
292
293 Attempting to create an invalid time currently causes a fatal error.
294 This may change in future version of this module.
295
296 * DateTime->from_epoch( epoch => $epoch, ... )
297 This class method can be used to construct a new DateTime object
298 from an epoch time instead of components. Just as with the `new()'
299 method, it accepts "time_zone", "locale", and "formatter"
300 parameters.
301
302 If the epoch value is not an integer, the part after the decimal
303 will be converted to nanoseconds. This is done in order to be
304 compatible with `Time::HiRes'. If the floating portion extends past
305 9 decimal places, it will be truncated to nine, so that 1.1234567891
306 will become 1 second and 123,456,789 nanoseconds.
307
308 By default, the returned object will be in the UTC time zone.
309
310 * DateTime->now( ... )
311 This class method is equivalent to calling `from_epoch()' with the
312 value returned from Perl's `time()' function. Just as with the
313 `new()' method, it accepts "time_zone" and "locale" parameters.
314
315 By default, the returned object will be in the UTC time zone.
316
317 * DateTime->today( ... )
318 This class method is equivalent to:
319
320 DateTime->now->truncate( to => 'day' );
321
322 * DateTime->from_object( object => $object, ... )
323 This class method can be used to construct a new DateTime object
324 from any object that implements the `utc_rd_values()' method. All
325 `DateTime::Calendar' modules must implement this method in order to
326 provide cross-calendar compatibility. This method accepts a "locale"
327 and "formatter" parameter
328
329 If the object passed to this method has a `time_zone()' method, that
330 is used to set the time zone of the newly created `DateTime.pm'
331 object.
332
333 Otherwise, the returned object will be in the floating time zone.
334
335 * DateTime->last_day_of_month( ... )
336 This constructor takes the same arguments as can be given to the
337 `new()' method, except for "day". Additionally, both "year" and
338 "month" are required.
339
340 * DateTime->from_day_of_year( ... )
341 This constructor takes the same arguments as can be given to the
342 `new()' method, except that it does not accept a "month" or "day"
343 argument. Instead, it requires both "year" and "day_of_year". The
344 day of year must be between 1 and 366, and 366 is only allowed for
345 leap years.
346
347 * $dt->clone()
348 This object method returns a new object that is replica of the
349 object upon which the method is called.
350
351 "Get" Methods
352 This class has many methods for retrieving information about an object.
353
354 * $dt->year()
355 Returns the year.
356
357 * $dt->ce_year()
358 Returns the year according to the BCE/CE numbering system. The year
359 before year 1 in this system is year -1, aka "1 BCE".
360
361 * $dt->era_name()
362 Returns the long name of the current era, something like "Before
363 Christ". See the Locales section for more details.
364
365 * $dt->era_abbr()
366 Returns the abbreviated name of the current era, something like
367 "BC". See the Locales section for more details.
368
369 * $dt->christian_era()
370 Returns a string, either "BC" or "AD", according to the year.
371
372 * $dt->secular_era()
373 Returns a string, either "BCE" or "CE", according to the year.
374
375 * $dt->year_with_era()
376 Returns a string containing the year immediately followed by its era
377 abbreviation. The year is the absolute value of `ce_year()', so that
378 year 1 is "1AD" and year 0 is "1BC".
379
380 * $dt->year_with_christian_era()
381 Like `year_with_era()', but uses the christian_era() to get the era
382 name.
383
384 * $dt->year_with_secular_era()
385 Like `year_with_era()', but uses the secular_era() method to get the
386 era name.
387
388 * $dt->month()
389 * $dt->mon()
390 Returns the month of the year, from 1..12.
391
392 * $dt->month_name()
393 Returns the name of the current month. See the Locales section for
394 more details.
395
396 * $dt->month_abbr()
397 Returns the abbreviated name of the current month. See the Locales
398 section for more details.
399
400 * $dt->day_of_month()
401 * $dt->day()
402 * $dt->mday()
403 Returns the day of the month, from 1..31.
404
405 * $dt->day_of_week()
406 * $dt->wday()
407 * $dt->dow()
408 Returns the day of the week as a number, from 1..7, with 1 being
409 Monday and 7 being Sunday.
410
411 * $dt->local_day_of_week()
412 Returns the day of the week as a number, from 1..7. The day
413 corresponding to 1 will vary based on the locale.
414
415 * $dt->day_name()
416 Returns the name of the current day of the week. See the Locales
417 section for more details.
418
419 * $dt->day_abbr()
420 Returns the abbreviated name of the current day of the week. See the
421 Locales section for more details.
422
423 * $dt->day_of_year()
424 * $dt->doy()
425 Returns the day of the year.
426
427 * $dt->quarter()
428 Returns the quarter of the year, from 1..4.
429
430 * $dt->quarter_name()
431 Returns the name of the current quarter. See the Locales section for
432 more details.
433
434 * $dt->quarter_abbr()
435 Returns the abbreviated name of the current quarter. See the Locales
436 section for more details.
437
438 * $dt->day_of_quarter()
439 * $dt->doq()
440 Returns the day of the quarter.
441
442 * $dt->weekday_of_month()
443 Returns a number from 1..5 indicating which week day of the month
444 this is. For example, June 9, 2003 is the second Monday of the
445 month, and so this method returns 2 for that day.
446
447 * $dt->ymd( $optional_separator ) - also $dt->date(...)
448 * $dt->mdy( $optional_separator )
449 * $dt->dmy( $optional_separator )
450 Each method returns the year, month, and day, in the order indicated
451 by the method name. Years are zero-padded to four digits. Months and
452 days are 0-padded to two digits.
453
454 By default, the values are separated by a dash (-), but this can be
455 overridden by passing a value to the method.
456
457 * $dt->hour()
458 Returns the hour of the day, from 0..23.
459
460 * $dt->hour_1()
461 Returns the hour of the day, from 1..24.
462
463 * $dt->hour_12()
464 Returns the hour of the day, from 1..12.
465
466 * $dt->hour_12_0()
467 Returns the hour of the day, from 0..11.
468
469 * $dt->am_or_pm()
470 Returns the appropriate localized abbreviation, depending on the
471 current hour.
472
473 * $dt->minute()
474 * $dt->min()
475 Returns the minute of the hour, from 0..59.
476
477 * $dt->second()
478 * $dt->sec()
479 Returns the second, from 0..61. The values 60 and 61 are used for
480 leap seconds.
481
482 * $dt->fractional_second()
483 Returns the second, as a real number from 0.0 until 61.999999999
484
485 The values 60 and 61 are used for leap seconds.
486
487 * $dt->millisecond()
488 Returns the fractional part of the second as milliseconds (1E-3
489 seconds).
490
491 Half a second is 500 milliseconds.
492
493 * $dt->microsecond()
494 Returns the fractional part of the second as microseconds (1E-6
495 seconds). This value will be rounded to an integer.
496
497 Half a second is 500_000 microseconds. This value will be rounded to
498 an integer.
499
500 * $dt->nanosecond()
501 Returns the fractional part of the second as nanoseconds (1E-9
502 seconds).
503
504 Half a second is 500_000_000 nanoseconds.
505
506 * $dt->hms( $optional_separator )
507 * $dt->time( $optional_separator )
508 Returns the hour, minute, and second, all zero-padded to two digits.
509 If no separator is specified, a colon (:) is used by default.
510
511 * $dt->datetime()
512 * $dt->iso8601()
513 This method is equivalent to:
514
515 $dt->ymd('-') . 'T' . $dt->hms(':')
516
517 * $dt->is_leap_year()
518 This method returns a true or false indicating whether or not the
519 datetime object is in a leap year.
520
521 * $dt->week()
522 ($week_year, $week_number) = $dt->week;
523
524 Returns information about the calendar week which contains this
525 datetime object. The values returned by this method are also
526 available separately through the week_year and week_number methods.
527
528 The first week of the year is defined by ISO as the one which
529 contains the fourth day of January, which is equivalent to saying
530 that it's the first week to overlap the new year by at least four
531 days.
532
533 Typically the week year will be the same as the year that the object
534 is in, but dates at the very beginning of a calendar year often end
535 up in the last week of the prior year, and similarly, the final few
536 days of the year may be placed in the first week of the next year.
537
538 * $dt->week_year()
539 Returns the year of the week.
540
541 * $dt->week_number()
542 Returns the week of the year, from 1..53.
543
544 * $dt->week_of_month()
545 The week of the month, from 0..5. The first week of the month is the
546 first week that contains a Thursday. This is based on the ICU
547 definition of week of month, and correlates to the ISO8601 week of
548 year definition. A day in the week *before* the week with the first
549 Thursday will be week 0.
550
551 * $dt->jd()
552 * $dt->mjd()
553 These return the Julian Day and Modified Julian Day, respectively.
554 The value returned is a floating point number. The fractional
555 portion of the number represents the time portion of the datetime.
556
557 * $dt->time_zone()
558 This returns the `DateTime::TimeZone' object for the datetime
559 object.
560
561 * $dt->offset()
562 This returns the offset from UTC, in seconds, of the datetime object
563 according to the time zone.
564
565 * $dt->is_dst()
566 Returns a boolean indicating whether or not the datetime object is
567 currently in Daylight Saving Time or not.
568
569 * $dt->time_zone_long_name()
570 This is a shortcut for `$dt->time_zone->name'. It's provided so that
571 one can use "%{time_zone_long_name}" as a strftime format specifier.
572
573 * $dt->time_zone_short_name()
574 This method returns the time zone abbreviation for the current time
575 zone, such as "PST" or "GMT". These names are not definitive, and
576 should not be used in any application intended for general use by
577 users around the world.
578
579 * $dt->strftime( $format, ... )
580 This method implements functionality similar to the `strftime()'
581 method in C. However, if given multiple format strings, then it will
582 return multiple scalars, one for each format string.
583
584 See the strftime Patterns section for a list of all possible
585 strftime patterns.
586
587 If you give a pattern that doesn't exist, then it is simply treated
588 as text.
589
590 * $dt->format_cldr( $format, ... )
591 This method implements formatting based on the CLDR date patterns.
592 If given multiple format strings, then it will return multiple
593 scalars, one for each format string.
594
595 See the CLDR Patterns section for a list of all possible CLDR
596 patterns.
597
598 If you give a pattern that doesn't exist, then it is simply treated
599 as text.
600
601 * $dt->epoch()
602 Return the UTC epoch value for the datetime object. Internally, this
603 is implemented using `Time::Local', which uses the Unix epoch even
604 on machines with a different epoch (such as MacOS). Datetimes before
605 the start of the epoch will be returned as a negative number.
606
607 The return value from this method is always an integer.
608
609 Since the epoch does not account for leap seconds, the epoch time
610 for 1972-12-31T23:59:60 (UTC) is exactly the same as that for
611 1973-01-01T00:00:00.
612
613 This module uses `Time::Local' to calculate the epoch, which may or
614 may not handle epochs before 1904 or after 2038 (depending on the
615 size of your system's integers, and whether or not Perl was compiled
616 with 64-bit int support).
617
618 * $dt->hires_epoch()
619 Returns the epoch as a floating point number. The floating point
620 portion of the value represents the nanosecond value of the object.
621 This method is provided for compatibility with the `Time::HiRes'
622 module.
623
624 * $dt->is_finite()
625 * $dt->is_infinite
626 These methods allow you to distinguish normal datetime objects from
627 infinite ones. Infinite datetime objects are documented in
628 DateTime::Infinite.
629
630 * $dt->utc_rd_values()
631 Returns the current UTC Rata Die days, seconds, and nanoseconds as a
632 three element list. This exists primarily to allow other calendar
633 modules to create objects based on the values provided by this
634 object.
635
636 * $dt->local_rd_values()
637 Returns the current local Rata Die days, seconds, and nanoseconds as
638 a three element list. This exists for the benefit of other modules
639 which might want to use this information for date math, such as
640 `DateTime::Event::Recurrence'.
641
642 * $dt->leap_seconds()
643 Returns the number of leap seconds that have happened up to the
644 datetime represented by the object. For floating datetimes, this
645 always returns 0.
646
647 * $dt->utc_rd_as_seconds()
648 Returns the current UTC Rata Die days and seconds purely as seconds.
649 This number ignores any fractional seconds stored in the object, as
650 well as leap seconds.
651
652 * $dt->local_rd_as_seconds() - deprecated
653 Returns the current local Rata Die days and seconds purely as
654 seconds. This number ignores any fractional seconds stored in the
655 object, as well as leap seconds.
656
657 * $dt->locale()
658 Returns the current locale object.
659
660 * $dt->formatter()
661 Returns current formatter object or class. See Formatters And
662 Stringification for details.
663
664 "Set" Methods
665 The remaining methods provided by `DateTime.pm', except where otherwise
666 specified, return the object itself, thus making method chaining
667 possible. For example:
668
669 my $dt = DateTime->now->set_time_zone( 'Australia/Sydney' );
670
671 my $first = DateTime
672 ->last_day_of_month( year => 2003, month => 3 )
673 ->add( days => 1 )
674 ->subtract( seconds => 1 );
675
676 * $dt->set( .. )
677 This method can be used to change the local components of a date
678 time, or its locale. This method accepts any parameter allowed by
679 the `new()' method except for "time_zone". Time zones may be set
680 using the `set_time_zone()' method.
681
682 This method performs parameters validation just as is done in the
683 `new()' method.
684
685 * $dt->set_year()
686 * $dt->set_month()
687 * $dt->set_day()
688 * $dt->set_hour()
689 * $dt->set_minute()
690 * $dt->set_second()
691 * $dt->set_nanosecond()
692 * $dt->set_locale()
693 These are shortcuts to calling `set()' with a single key. They all
694 take a single parameter.
695
696 * $dt->truncate( to => ... )
697 This method allows you to reset some of the local time components in
698 the object to their "zero" values. The "to" parameter is used to
699 specify which values to truncate, and it may be one of "year",
700 "month", "week", "day", "hour", "minute", or "second". For example,
701 if "month" is specified, then the local day becomes 1, and the hour,
702 minute, and second all become 0.
703
704 If "week" is given, then the datetime is set to the beginning of the
705 week in which it occurs, and the time components are all set to 0.
706
707 * $dt->set_time_zone( $tz )
708 This method accepts either a time zone object or a string that can
709 be passed as the "name" parameter to `DateTime::TimeZone->new()'. If
710 the new time zone's offset is different from the old time zone, then
711 the *local* time is adjusted accordingly.
712
713 For example:
714
715 my $dt = DateTime->new( year => 2000, month => 5, day => 10,
716 hour => 15, minute => 15,
717 time_zone => 'America/Los_Angeles', );
718
719 print $dt->hour; # prints 15
720
721 $dt->set_time_zone( 'America/Chicago' );
722
723 print $dt->hour; # prints 17
724
725 If the old time zone was a floating time zone, then no adjustments
726 to the local time are made, except to account for leap seconds. If
727 the new time zone is floating, then the *UTC* time is adjusted in
728 order to leave the local time untouched.
729
730 Fans of Tsai Ming-Liang's films will be happy to know that this does
731 work:
732
733 my $dt = DateTime->now( time_zone => 'Asia/Taipei' );
734
735 $dt->set_time_zone( 'Europe/Paris' );
736
737 Yes, now we can know "ni3 na4 bian1 ji2dian3?"
738
739 * $dt->set_formatter( $formatter )
740 Set the formatter for the object. See Formatters And Stringification
741 for details.
742
743 Math Methods
744 Like the set methods, math related methods always return the object
745 itself, to allow for chaining:
746
747 $dt->add( days => 1 )->subtract( seconds => 1 );
748
749 * $dt->duration_class()
750 This returns `DateTime::Duration', but exists so that a subclass of
751 `DateTime.pm' can provide a different value.
752
753 * $dt->add_duration( $duration_object )
754 This method adds a `DateTime::Duration' to the current datetime. See
755 the DateTime::Duration docs for more details.
756
757 * $dt->add( DateTime::Duration->new parameters )
758 This method is syntactic sugar around the `add_duration()' method.
759 It simply creates a new `DateTime::Duration' object using the
760 parameters given, and then calls the `add_duration()' method.
761
762 * $dt->subtract_duration( $duration_object )
763 When given a `DateTime::Duration' object, this method simply calls
764 `invert()' on that object and passes that new duration to the
765 `add_duration' method.
766
767 * $dt->subtract( DateTime::Duration->new parameters )
768 Like `add()', this is syntactic sugar for the `subtract_duration()'
769 method.
770
771 * $dt->subtract_datetime( $datetime )
772 This method returns a new `DateTime::Duration' object representing
773 the difference between the two dates. The duration is relative to
774 the object from which `$datetime' is subtracted. For example:
775
776 2003-03-15 00:00:00.00000000
777 - 2003-02-15 00:00:00.00000000
778
779 -------------------------------
780
781 = 1 month
782
783 Note that this duration is not an absolute measure of the amount of
784 time between the two datetimes, because the length of a month
785 varies, as well as due to the presence of leap seconds.
786
787 The returned duration may have deltas for months, days, minutes,
788 seconds, and nanoseconds.
789
790 * $dt->delta_md( $datetime )
791 * $dt->delta_days( $datetime )
792 Each of these methods returns a new `DateTime::Duration' object
793 representing some portion of the difference between two datetimes.
794 The `delta_md()' method returns a duration which contains only the
795 month and day portions of the duration is represented. The
796 `delta_days()' method returns a duration which contains only days.
797
798 The `delta_md' and `delta_days' methods truncate the duration so
799 that any fractional portion of a day is ignored. Both of these
800 methods operate on the date portion of a datetime only, and so
801 effectively ignore the time zone.
802
803 Unlike the subtraction methods, these methods always return a
804 positive (or zero) duration.
805
806 * $dt->delta_ms( $datetime )
807 Returns a duration which contains only minutes and seconds. Any day
808 and month differences to minutes are converted to minutes and
809 seconds. This method also always return a positive (or zero)
810 duration.
811
812 * $dt->subtract_datetime_absolute( $datetime )
813 This method returns a new `DateTime::Duration' object representing
814 the difference between the two dates in seconds and nanoseconds.
815 This is the only way to accurately measure the absolute amount of
816 time between two datetimes, since units larger than a second do not
817 represent a fixed number of seconds.
818
819 Class Methods
820 * DateTime->DefaultLocale( $locale )
821 This can be used to specify the default locale to be used when
822 creating DateTime objects. If unset, then "en_US" is used.
823
824 * DateTime->compare( $dt1, $dt2 )
825 * DateTime->compare_ignore_floating( $dt1, $dt2 )
826 $cmp = DateTime->compare( $dt1, $dt2 );
827
828 $cmp = DateTime->compare_ignore_floating( $dt1, $dt2 );
829
830 Compare two DateTime objects. The semantics are compatible with
831 Perl's `sort()' function; it returns -1 if $dt1 < $dt2, 0 if $dt1 ==
832 $dt2, 1 if $dt1 > $dt2.
833
834 If one of the two DateTime objects has a floating time zone, it will
835 first be converted to the time zone of the other object. This is
836 what you want most of the time, but it can lead to inconsistent
837 results when you compare a number of DateTime objects, some of which
838 are floating, and some of which are in other time zones.
839
840 If you want to have consistent results (because you want to sort a
841 number of objects, for example), you can use the
842 `compare_ignore_floating()' method:
843
844 @dates = sort { DateTime->compare_ignore_floating($a, $b) } @dates;
845
846 In this case, objects with a floating time zone will be sorted as if
847 they were UTC times.
848
849 Since DateTime objects overload comparison operators, this:
850
851 @dates = sort @dates;
852
853 is equivalent to this:
854
855 @dates = sort { DateTime->compare($a, $b) } @dates;
856
857 DateTime objects can be compared to any other calendar class that
858 implements the `utc_rd_values()' method.
859
860 How Datetime Math is Done
861 It's important to have some understanding of how datetime math is
862 implemented in order to effectively use this module and
863 `DateTime::Duration'.
864
865 Making Things Simple
866 If you want to simplify your life and not have to think too hard about
867 the nitty-gritty of datetime math, I have several recommendations:
868
869 * use the floating time zone
870 If you do not care about time zones or leap seconds, use the
871 "floating" timezone:
872
873 my $dt = DateTime->now( time_zone => 'floating' );
874
875 Math done on two objects in the floating time zone produces very
876 predictable results.
877
878 * use UTC for all calculations
879 If you do care about time zones (particularly DST) or leap seconds,
880 try to use non-UTC time zones for presentation and user input only.
881 Convert to UTC immediately and convert back to the local time zone
882 for presentation:
883
884 my $dt = DateTime->new( %user_input, time_zone => $user_tz );
885 $dt->set_time_zone('UTC');
886
887 # do various operations - store it, retrieve it, add, subtract, etc.
888
889 $dt->set_time_zone($user_tz);
890 print $dt->datetime;
891
892 * math on non-UTC time zones
893 If you need to do date math on objects with non-UTC time zones,
894 please read the caveats below carefully. The results `DateTime.pm'
895 produces are predictable and correct, and mostly intuitive, but
896 datetime math gets very ugly when time zones are involved, and there
897 are a few strange corner cases involving subtraction of two
898 datetimes across a DST change.
899
900 If you can always use the floating or UTC time zones, you can skip
901 ahead to Leap Seconds and Date Math
902
903 * date vs datetime math
904 If you only care about the date (calendar) portion of a datetime,
905 you should use either `delta_md()' or `delta_days()', not
906 `subtract_datetime()'. This will give predictable, unsurprising
907 results, free from DST-related complications.
908
909 * subtract_datetime() and add_duration()
910 You must convert your datetime objects to the UTC time zone before
911 doing date math if you want to make sure that the following formulas
912 are always true:
913
914 $dt2 - $dt1 = $dur
915 $dt1 + $dur = $dt2
916 $dt2 - $dur = $dt1
917
918 Note that using `delta_days' ensures that this formula always works,
919 regardless of the timezone of the objects involved, as does using
920 `subtract_datetime_absolute()'. Other methods of subtraction are not
921 always reversible.
922
923 Adding a Duration to a Datetime
924 The parts of a duration can be broken down into five parts. These are
925 months, days, minutes, seconds, and nanoseconds. Adding one month to a
926 date is different than adding 4 weeks or 28, 29, 30, or 31 days.
927 Similarly, due to DST and leap seconds, adding a day can be different
928 than adding 86,400 seconds, and adding a minute is not exactly the same
929 as 60 seconds.
930
931 We cannot convert between these units, except for seconds and
932 nanoseconds, because there is no fixed conversion between the two units,
933 because of things like leap seconds, DST changes, etc.
934
935 `DateTime.pm' always adds (or subtracts) days, then months, minutes, and
936 then seconds and nanoseconds. If there are any boundary overflows, these
937 are normalized at each step. For the days and months the local (not UTC)
938 values are used. For minutes and seconds, the local values are used.
939 This generally just works.
940
941 This means that adding one month and one day to February 28, 2003 will
942 produce the date April 1, 2003, not March 29, 2003.
943
944 my $dt = DateTime->new( year => 2003, month => 2, day => 28 );
945
946 $dt->add( months => 1, days => 1 );
947
948 # 2003-04-01 - the result
949
950 On the other hand, if we add months first, and then separately add days,
951 we end up with March 29, 2003:
952
953 $dt->add( months => 1 )->add( days => 1 );
954
955 # 2003-03-29
956
957 We see similar strangeness when math crosses a DST boundary:
958
959 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
960 hour => 1, minute => 58,
961 time_zone => "America/Chicago",
962 );
963
964 $dt->add( days => 1, minutes => 3 );
965 # 2003-04-06 02:01:00
966
967 $dt->add( minutes => 3 )->add( days => 1 );
968 # 2003-04-06 03:01:00
969
970 Note that if you converted the datetime object to UTC first you would
971 get predictable results.
972
973 If you want to know how many seconds a duration object represents, you
974 have to add it to a datetime to find out, so you could do:
975
976 my $now = DateTime->now( time_zone => 'UTC' );
977 my $later = $now->clone->add_duration($duration);
978
979 my $seconds_dur = $later->subtract_datetime_absolute($now);
980
981 This returns a duration which only contains seconds and nanoseconds.
982
983 If we were add the duration to a different datetime object we might get
984 a different number of seconds.
985
986 If you need to do lots of work with durations, take a look at Rick
987 Measham's `DateTime::Format::Duration' module, which lets you present
988 information from durations in many useful ways.
989
990 There are other subtract/delta methods in DateTime.pm to generate
991 different types of durations. These methods are `subtract_datetime()',
992 `subtract_datetime_absolute()', `delta_md()', `delta_days()', and
993 `delta_ms()'.
994
995 Datetime Subtraction
996 Date subtraction is done solely based on the two object's local
997 datetimes, with one exception to handle DST changes. Also, if the two
998 datetime objects are in different time zones, one of them is converted
999 to the other's time zone first before subtraction. This is best
1000 explained through examples:
1001
1002 The first of these probably makes the most sense:
1003
1004 my $dt1 = DateTime->new( year => 2003, month => 5, day => 6,
1005 time_zone => 'America/Chicago',
1006 );
1007 # not DST
1008
1009 my $dt2 = DateTime->new( year => 2003, month => 11, day => 6,
1010 time_zone => 'America/Chicago',
1011 );
1012 # is DST
1013
1014 my $dur = $dt2->subtract_datetime($dt1);
1015 # 6 months
1016
1017 Nice and simple.
1018
1019 This one is a little trickier, but still fairly logical:
1020
1021 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1022 hour => 1, minute => 58,
1023 time_zone => "America/Chicago",
1024 );
1025 # is DST
1026
1027 my $dt2 = DateTime->new( year => 2003, month => 4, day => 7,
1028 hour => 2, minute => 1,
1029 time_zone => "America/Chicago",
1030 );
1031 # not DST
1032
1033 my $dur = $dt2->subtract_datetime($dt1);
1034 # 2 days and 3 minutes
1035
1036 Which contradicts the result this one gives, even though they both make
1037 sense:
1038
1039 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1040 hour => 1, minute => 58,
1041 time_zone => "America/Chicago",
1042 );
1043 # is DST
1044
1045 my $dt2 = DateTime->new( year => 2003, month => 4, day => 6,
1046 hour => 3, minute => 1,
1047 time_zone => "America/Chicago",
1048 );
1049 # not DST
1050
1051 my $dur = $dt2->subtract_datetime($dt1);
1052 # 1 day and 3 minutes
1053
1054 This last example illustrates the "DST" exception mentioned earlier. The
1055 exception accounts for the fact 2003-04-06 only lasts 23 hours.
1056
1057 And finally:
1058
1059 my $dt2 = DateTime->new( year => 2003, month => 10, day => 26,
1060 hour => 1,
1061 time_zone => 'America/Chicago',
1062 );
1063
1064 my $dt1 = $dt2->clone->subtract( hours => 1 );
1065
1066 my $dur = $dt2->subtract_datetime($dt1);
1067 # 60 minutes
1068
1069 This seems obvious until you realize that subtracting 60 minutes from
1070 `$dt2' in the above example still leaves the clock time at "01:00:00".
1071 This time we are accounting for a 25 hour day.
1072
1073 Reversibility
1074 Date math operations are not always reversible. This is because of the
1075 way that addition operations are ordered. As was discussed earlier,
1076 adding 1 day and 3 minutes in one call to `add()' is not the same as
1077 first adding 3 minutes and 1 day in two separate calls.
1078
1079 If we take a duration returned from `subtract_datetime()' and then try
1080 to add or subtract that duration from one of the datetimes we just used,
1081 we sometimes get interesting results:
1082
1083 my $dt1 = DateTime->new( year => 2003, month => 4, day => 5,
1084 hour => 1, minute => 58,
1085 time_zone => "America/Chicago",
1086 );
1087
1088 my $dt2 = DateTime->new( year => 2003, month => 4, day => 6,
1089 hour => 3, minute => 1,
1090 time_zone => "America/Chicago",
1091 );
1092
1093 my $dur = $dt2->subtract_datetime($dt1);
1094 # 1 day and 3 minutes
1095
1096 $dt1->add_duration($dur);
1097 # gives us $dt2
1098
1099 $dt2->subtract_duration($dur);
1100 # gives us 2003-04-05 02:58:00 - 1 hour later than $dt1
1101
1102 The `subtract_dauration()' operation gives us a (perhaps) unexpected
1103 answer because it first subtracts one day to get 2003-04-05T03:01:00 and
1104 then subtracts 3 minutes to get the final result.
1105
1106 If we explicitly reverse the order we can get the original value of
1107 `$dt1'. This can be facilitated by `DateTime::Duration''s
1108 `calendar_duration()' and `clock_duration()' methods:
1109
1110 $dt2->subtract_duration( $dur->clock_duration )
1111 ->subtract_duration( $dur->calendar_duration );
1112
1113 Leap Seconds and Date Math
1114 The presence of leap seconds can cause even more anomalies in date math.
1115 For example, the following is a legal datetime:
1116
1117 my $dt = DateTime->new( year => 1972, month => 12, day => 31,
1118 hour => 23, minute => 59, second => 60,
1119 time_zone => 'UTC' );
1120
1121 If we do the following:
1122
1123 $dt->add( months => 1 );
1124
1125 Then the datetime is now "1973-02-01 00:00:00", because there is no
1126 23:59:60 on 1973-01-31.
1127
1128 Leap seconds also force us to distinguish between minutes and seconds
1129 during date math. Given the following datetime:
1130
1131 my $dt = DateTime->new( year => 1972, month => 12, day => 31,
1132 hour => 23, minute => 59, second => 30,
1133 time_zone => 'UTC' );
1134
1135 we will get different results when adding 1 minute than we get if we add
1136 60 seconds. This is because in this case, the last minute of the day,
1137 beginning at 23:59:00, actually contains 61 seconds.
1138
1139 Here are the results we get:
1140
1141 # 1972-12-31 23:59:30 - our starting datetime
1142
1143 $dt->clone->add( minutes => 1 );
1144 # 1973-01-01 00:00:30 - one minute later
1145
1146 $dt->clone->add( seconds => 60 );
1147 # 1973-01-01 00:00:29 - 60 seconds later
1148
1149 $dt->clone->add( seconds => 61 );
1150 # 1973-01-01 00:00:30 - 61 seconds later
1151
1152 Local vs. UTC and 24 hours vs. 1 day
1153 When math crosses a daylight saving boundary, a single day may have more
1154 or less than 24 hours.
1155
1156 For example, if you do this:
1157
1158 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
1159 hour => 2,
1160 time_zone => 'America/Chicago',
1161 );
1162 $dt->add( days => 1 );
1163
1164 then you will produce an *invalid* local time, and therefore an
1165 exception will be thrown.
1166
1167 However, this works:
1168
1169 my $dt = DateTime->new( year => 2003, month => 4, day => 5,
1170 hour => 2,
1171 time_zone => 'America/Chicago',
1172 );
1173 $dt->add( hours => 24 );
1174
1175 and produces a datetime with the local time of "03:00".
1176
1177 If all this makes your head hurt, there is a simple alternative. Just
1178 convert your datetime object to the "UTC" time zone before doing date
1179 math on it, and switch it back to the local time zone afterwards. This
1180 avoids the possibility of having date math throw an exception, and makes
1181 sure that 1 day equals 24 hours. Of course, this may not always be
1182 desirable, so caveat user!
1183
1184 Overloading
1185 This module explicitly overloads the addition (+), subtraction (-),
1186 string and numeric comparison operators. This means that the following
1187 all do sensible things:
1188
1189 my $new_dt = $dt + $duration_obj;
1190
1191 my $new_dt = $dt - $duration_obj;
1192
1193 my $duration_obj = $dt - $new_dt;
1194
1195 foreach my $dt ( sort @dts ) { ... }
1196
1197 Additionally, the fallback parameter is set to true, so other derivable
1198 operators (+=, -=, etc.) will work properly. Do not expect increment
1199 (++) or decrement (--) to do anything useful.
1200
1201 If you attempt to sort DateTime objects with non-DateTime.pm objects or
1202 scalars (strings, number, whatever) then an exception will be thrown.
1203 Using the string comparison operators, `eq' or `ne', to compare a
1204 DateTime.pm always returns false.
1205
1206 The module also overloads stringification to use the `iso8601()' method.
1207
1208 Formatters And Stringification
1209 You can optionally specify a "formatter", which is usually a
1210 DateTime::Format::* object/class, to control the stringification of the
1211 DateTime object.
1212
1213 Any of the constructor methods can accept a formatter argument:
1214
1215 my $formatter = DateTime::Format::Strptime->new(...);
1216 my $dt = DateTime->new(year => 2004, formatter => $formatter);
1217
1218 Or, you can set it afterwards:
1219
1220 $dt->set_formatter($formatter);
1221 $formatter = $dt->formatter();
1222
1223 Once you set the formatter, the overloaded stringification method will
1224 use the formatter. If unspecified, the `iso8601()' method is used.
1225
1226 A formatter can be handy when you know that in your application you want
1227 to stringify your DateTime objects into a special format all the time,
1228 for example to a different language.
1229
1230 If you provide a formatter class name or object, it must implement a
1231 `format_datetime' method. This method will be called with just the
1232 DateTime object as its argument.
1233
1234 strftime Patterns
1235 The following patterns are allowed in the format string given to the
1236 `$dt->strftime()' method:
1237
1238 * %a
1239 The abbreviated weekday name.
1240
1241 * %A
1242 The full weekday name.
1243
1244 * %b
1245 The abbreviated month name.
1246
1247 * %B
1248 The full month name.
1249
1250 * %c
1251 The default datetime format for the object's locale.
1252
1253 * %C
1254 The century number (year/100) as a 2-digit integer.
1255
1256 * %d
1257 The day of the month as a decimal number (range 01 to 31).
1258
1259 * %D
1260 Equivalent to %m/%d/%y. This is not a good standard format if you
1261 want folks from both the United States and the rest of the world to
1262 understand the date!
1263
1264 * %e
1265 Like %d, the day of the month as a decimal number, but a leading
1266 zero is replaced by a space.
1267
1268 * %F
1269 Equivalent to %Y-%m-%d (the ISO 8601 date format)
1270
1271 * %G
1272 The ISO 8601 year with century as a decimal number. The 4-digit year
1273 corresponding to the ISO week number (see %V). This has the same
1274 format and value as %Y, except that if the ISO week number belongs
1275 to the previous or next year, that year is used instead. (TZ)
1276
1277 * %g
1278 Like %G, but without century, i.e., with a 2-digit year (00-99).
1279
1280 * %h
1281 Equivalent to %b.
1282
1283 * %H
1284 The hour as a decimal number using a 24-hour clock (range 00 to 23).
1285
1286 * %I
1287 The hour as a decimal number using a 12-hour clock (range 01 to 12).
1288
1289 * %j
1290 The day of the year as a decimal number (range 001 to 366).
1291
1292 * %k
1293 The hour (24-hour clock) as a decimal number (range 0 to 23); single
1294 digits are preceded by a blank. (See also %H.)
1295
1296 * %l
1297 The hour (12-hour clock) as a decimal number (range 1 to 12); single
1298 digits are preceded by a blank. (See also %I.)
1299
1300 * %m
1301 The month as a decimal number (range 01 to 12).
1302
1303 * %M
1304 The minute as a decimal number (range 00 to 59).
1305
1306 * %n
1307 A newline character.
1308
1309 * %N
1310 The fractional seconds digits. Default is 9 digits (nanoseconds).
1311
1312 %3N milliseconds (3 digits)
1313 %6N microseconds (6 digits)
1314 %9N nanoseconds (9 digits)
1315
1316 * %p
1317 Either `AM' or `PM' according to the given time value, or the
1318 corresponding strings for the current locale. Noon is treated as
1319 `pm' and midnight as `am'.
1320
1321 * %P
1322 Like %p but in lowercase: `am' or `pm' or a corresponding string for
1323 the current locale.
1324
1325 * %r
1326 The time in a.m. or p.m. notation. In the POSIX locale this is
1327 equivalent to `%I:%M:%S %p'.
1328
1329 * %R
1330 The time in 24-hour notation (%H:%M). (SU) For a version including
1331 the seconds, see %T below.
1332
1333 * %s
1334 The number of seconds since the epoch.
1335
1336 * %S
1337 The second as a decimal number (range 00 to 61).
1338
1339 * %t
1340 A tab character.
1341
1342 * %T
1343 The time in 24-hour notation (%H:%M:%S).
1344
1345 * %u
1346 The day of the week as a decimal, range 1 to 7, Monday being 1. See
1347 also %w.
1348
1349 * %U
1350 The week number of the current year as a decimal number, range 00 to
1351 53, starting with the first Sunday as the first day of week 01. See
1352 also %V and %W.
1353
1354 * %V
1355 The ISO 8601:1988 week number of the current year as a decimal
1356 number, range 01 to 53, where week 1 is the first week that has at
1357 least 4 days in the current year, and with Monday as the first day
1358 of the week. See also %U and %W.
1359
1360 * %w
1361 The day of the week as a decimal, range 0 to 6, Sunday being 0. See
1362 also %u.
1363
1364 * %W
1365 The week number of the current year as a decimal number, range 00 to
1366 53, starting with the first Monday as the first day of week 01.
1367
1368 * %x
1369 The default date format for the object's locale.
1370
1371 * %X
1372 The default time format for the object's locale.
1373
1374 * %y
1375 The year as a decimal number without a century (range 00 to 99).
1376
1377 * %Y
1378 The year as a decimal number including the century.
1379
1380 * %z
1381 The time-zone as hour offset from UTC. Required to emit
1382 RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
1383
1384 * %Z
1385 The time zone or name or abbreviation.
1386
1387 * %%
1388 A literal `%' character.
1389
1390 * %{method}
1391 Any method name may be specified using the format `%{method}' name
1392 where "method" is a valid `DateTime.pm' object method.
1393
1394 CLDR Patterns
1395 The CLDR pattern language is both more powerful and more complex than
1396 strftime. Unlike strftime patterns, you often have to explicitly escape
1397 text that you do not want formatted, as the patterns are simply letters
1398 without any prefix.
1399
1400 For example, "yyyy-MM-dd" is a valid CLDR pattern. If you want to
1401 include any lower or upper case ASCII characters as-is, you can surround
1402 them with single quotes ('). If you want to include a single quote, you
1403 must escape it as two single quotes ('').
1404
1405 'Today is ' EEEE
1406 'It is now' h 'o''clock' a
1407
1408 Spaces and any non-letter text will always be passed through as-is.
1409
1410 Many CLDR patterns which produce numbers will pad the number with
1411 leading zeroes depending on the length of the format specifier. For
1412 example, "h" represents the current hour from 1-12. If you specify "hh"
1413 then the 1-9 will have a leading zero prepended.
1414
1415 However, CLDR often uses five of a letter to represent the narrow form
1416 of a pattern. This inconsistency is necessary for backwards
1417 compatibility.
1418
1419 CLDR often distinguishes between the "format" and "stand-alone" forms of
1420 a pattern. The format pattern is used when the thing in question is
1421 being placed into a larger string. The stand-alone form is used when
1422 displaying that item by itself, for example in a calendar.
1423
1424 It also often provides three sizes for each item, wide (the full name),
1425 abbreviated, and narrow. The narrow form is often just a single
1426 character, for example "T" for "Tuesday", and may not be unique.
1427
1428 CLDR provides a fairly complex system for localizing time zones that we
1429 ignore entirely. The time zone patterns just use the information
1430 provided by `DateTime::TimeZone', and *do not follow the CLDR spec*.
1431
1432 The output of a CLDR pattern is always localized, when applicable.
1433
1434 CLDR provides the following patterns:
1435
1436 * G{1,3}
1437 The abbreviated era (BC, AD).
1438
1439 * GGGG
1440 The wide era (Before Christ, Anno Domini).
1441
1442 * GGGGG
1443 The narrow era, if it exists (and it mostly doesn't).
1444
1445 * y and y{3,}
1446 The year, zero-prefixed as needed. Negative years will start with a
1447 "-", and this will be included in the length calculation.
1448
1449 In other, words the "yyyyy" pattern will format year -1234 as
1450 "-1234", not "-01234".
1451
1452 * yy
1453 This is a special case. It always produces a two-digit year, so
1454 "1976" becomes "76". Negative years will start with a "-", making
1455 them one character longer.
1456
1457 * Y{1,}
1458 The week of the year, from `$dt->week_year()'.
1459
1460 * u{1,}
1461 Same as "y" except that "uu" is not a special case.
1462
1463 * Q{1,2}
1464 The quarter as a number (1..4).
1465
1466 * QQQ
1467 The abbreviated format form for the quarter.
1468
1469 * QQQQ
1470 The wide format form for the quarter.
1471
1472 * q{1,2}
1473 The quarter as a number (1..4).
1474
1475 * qqq
1476 The abbreviated stand-alone form for the quarter.
1477
1478 * qqqq
1479 The wide stand-alone form for the quarter.
1480
1481 * M{1,2]
1482 The numerical month.
1483
1484 * MMM
1485 The abbreviated format form for the month.
1486
1487 * MMMM
1488 The wide format form for the month.
1489
1490 * MMMMM
1491 The narrow format form for the month.
1492
1493 * L{1,2]
1494 The numerical month.
1495
1496 * LLL
1497 The abbreviated stand-alone form for the month.
1498
1499 * LLLL
1500 The wide stand-alone form for the month.
1501
1502 * LLLLL
1503 The narrow stand-alone form for the month.
1504
1505 * w{1,2}
1506 The week of the year, from `$dt->week_number()'.
1507
1508 * W The week of the month, from `$dt->week_of_month()'.
1509
1510 * d{1,2}
1511 The numeric day of of the month.
1512
1513 * D{1,3}
1514 The numeric day of of the year.
1515
1516 * F The day of the week in the month, from `$dt->weekday_of_month()'.
1517
1518 * g{1,}
1519 The modified Julian day, from `$dt->mjd()'.
1520
1521 * E{1,3} and eee
1522 The abbreviated format form for the day of the week.
1523
1524 * EEEE and eeee
1525 The wide format form for the day of the week.
1526
1527 * EEEEE and eeeee
1528 The narrow format form for the day of the week.
1529
1530 * e{1,2}
1531 The *local* numeric day of the week, from 1 to 7. This number
1532 depends on what day is considered the first day of the week, which
1533 varies by locale. For example, in the US, Sunday is the first day of
1534 the week, so this returns 2 for Monday.
1535
1536 * c The numeric day of the week from 1 to 7, treating Monday as the
1537 first of the week, regardless of locale.
1538
1539 * ccc
1540 The abbreviated stand-alone form for the day of the week.
1541
1542 * cccc
1543 The wide stand-alone form for the day of the week.
1544
1545 * ccccc
1546 The narrow format form for the day of the week.
1547
1548 * a The localized form of AM or PM for the time.
1549
1550 * h{1,2}
1551 The hour from 1-12.
1552
1553 * H{1,2}
1554 The hour from 0-23.
1555
1556 * K{1,2}
1557 The hour from 0-11.
1558
1559 * k{1,2}
1560 The hour from 1-24.
1561
1562 * j{1,2}
1563 The hour, in 12 or 24 hour form, based on the preferred form for the
1564 locale. In other words, this is equivalent to either "h{1,2}" or
1565 "H{1,2}".
1566
1567 * m{1,2}
1568 The minute.
1569
1570 * s{1,2}
1571 The second.
1572
1573 * S{1,}
1574 The fractional portion of the seconds, rounded based on the length
1575 of the specifier. This returned *without* a leading decimal point,
1576 but may have leading or trailing zeroes.
1577
1578 * A{1,}
1579 The millisecond of the day, based on the current time. In other
1580 words, if it is 12:00:00.00, this returns 43200000.
1581
1582 * z{1,3}
1583 The time zone short name.
1584
1585 * zzzz
1586 The time zone long name.
1587
1588 * Z{1,3}
1589 The time zone short name and the offset as one string, so something
1590 like "CDT-0500".
1591
1592 * ZZZZ
1593 The time zone long name.
1594
1595 * v{1,3}
1596 The time zone short name.
1597
1598 * vvvv
1599 The time zone long name.
1600
1601 * V{1,3}
1602 The time zone short name.
1603
1604 * VVVV
1605 The time zone long name.
1606
1607DateTime.pm and Storable
1608 DateTime implements Storable hooks in order to reduce the size of a
1609 serialized DateTime object.
1610
1611KNOWN BUGS
1612 The tests in 20infinite.t seem to fail on some machines, particularly on
1613 Win32. This appears to be related to Perl's internal handling of IEEE
1614 infinity and NaN, and seems to be highly platform/compiler/phase of moon
1615 dependent.
1616
1617 If you don't plan to use infinite datetimes you can probably ignore
1618 this. This will be fixed (somehow) in future versions.
1619
1620SUPPORT
1621 Support for this module is provided via the datetime@perl.org email
1622 list. See http://datetime.perl.org/?MailingList for details.
1623
1624 Please submit bugs to the CPAN RT system at
1625 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime or via email at
1626 bug-datetime@rt.cpan.org.
1627
1628DONATIONS
1629 If you'd like to thank me for the work I've done on this module, please
1630 consider making a "donation" to me via PayPal. I spend a lot of free
1631 time creating free software, and would appreciate any support you'd care
1632 to offer.
1633
1634 Please note that I am not suggesting that you must do this in order for
1635 me to continue working on this particular software. I will continue to
1636 do so, inasmuch as I have in the past, for as long as it interests me.
1637
1638 Similarly, a donation made in this way will probably not make me work on
1639 this software much more, unless I get so many donations that I can
1640 consider working on free software full time, which seems unlikely at
1641 best.
1642
1643 To donate, log into PayPal and send money to autarch@urth.org or use the
1644 button on this page: http://www.urth.org/~autarch/fs-donation.html
1645
1646AUTHOR
1647 Dave Rolsky <autarch@urth.org>
1648
1649 However, please see the CREDITS file for more details on who I really
1650 stole all the code from.
1651
1652COPYRIGHT
1653 Copyright (c) 2003-2009 David Rolsky. All rights reserved. This program
1654 is free software; you can redistribute it and/or modify it under the
1655 same terms as Perl itself.
1656
1657 Portions of the code in this distribution are derived from other works.
1658 Please see the CREDITS file for more details.
1659
1660 The full text of the license can be found in the LICENSE file included
1661 with this module.
1662
1663SEE ALSO
1664 datetime@perl.org mailing list
1665
1666 http://datetime.perl.org/
1667
1668