File Coverage

blib/lib/DateTime.pm
Criterion Covered Total %
statement 689 698 98.7
branch 297 326 91.1
condition 123 142 86.6
subroutine 177 178 99.4
pod 103 115 89.5
total 1389 1459 95.2


line stmt bran cond sub pod time code
1             ## no critic (Modules::ProhibitExcessMainComplexity)
2             package DateTime;
3              
4 49     49   4821667 use 5.008004;
  49         645  
5              
6 49     49   284 use strict;
  49         96  
  49         1020  
7 49     49   236 use warnings;
  49         110  
  49         1568  
8 49     49   291 use warnings::register;
  49         93  
  49         6826  
9 49     49   22935 use namespace::autoclean 0.19;
  49         835980  
  49         264  
10              
11             our $VERSION = '1.60';
12              
13 49     49   3715 use Carp;
  49         129  
  49         3121  
14 49     49   23881 use DateTime::Duration;
  49         198  
  49         1926  
15 49     49   378 use DateTime::Helpers;
  49         125  
  49         1408  
16 49     49   26562 use DateTime::Locale 1.06;
  49         3450379  
  49         2187  
17 49     49   27468 use DateTime::TimeZone 2.44;
  49         1802714  
  49         1813  
18 49     49   508 use DateTime::Types;
  49         151  
  49         458  
19 49     49   1624901 use POSIX qw( floor fmod );
  49         145  
  49         512  
20 49     49   81522 use Params::ValidationCompiler 0.26 qw( validation_for );
  49         1038  
  49         3018  
21 49     49   436 use Scalar::Util qw( blessed );
  49         141  
  49         3030  
22 49     49   28302 use Specio::Subs qw( Specio::Library::Builtins );
  49         768479  
  49         349  
23 49     49   1031350 use Try::Tiny;
  49         162  
  49         18169  
24              
25             ## no critic (Variables::ProhibitPackageVars)
26             our $IsPurePerl;
27              
28             {
29             my $loaded = 0;
30              
31             unless ( $ENV{PERL_DATETIME_PP} ) {
32             try {
33             require XSLoader;
34             XSLoader::load(
35             __PACKAGE__,
36             exists $DateTime::{VERSION} && ${ $DateTime::{VERSION} }
37             ? ${ $DateTime::{VERSION} }
38             : 42
39             );
40              
41             $loaded = 1;
42             $IsPurePerl = 0;
43             }
44             catch {
45             die $_ if $_ && $_ !~ /object version|loadable object/;
46             };
47             }
48              
49             if ($loaded) {
50             ## no critic (Variables::ProtectPrivateVars)
51             require DateTime::PPExtra
52             unless defined &DateTime::_normalize_tai_seconds;
53             }
54             else {
55             require DateTime::PP;
56             }
57             }
58              
59             # for some reason, overloading doesn't work unless fallback is listed
60             # early.
61             #
62             # 3rd parameter ( $_[2] ) means the parameters are 'reversed'.
63             # see: "Calling conventions for binary operations" in overload docs.
64             #
65             use overload (
66             fallback => 1,
67             '<=>' => '_compare_overload',
68             'cmp' => '_string_compare_overload',
69             q{""} => 'stringify',
70 39     39   2117 bool => sub {1},
71 49         866 '-' => '_subtract_overload',
72             '+' => '_add_overload',
73             'eq' => '_string_equals_overload',
74             'ne' => '_string_not_equals_overload',
75 49     49   513 );
  49         133  
76              
77             # Have to load this after overloading is defined, after BEGIN blocks
78             # or else weird crashes ensue
79             require DateTime::Infinite;
80              
81             sub MAX_NANOSECONDS () {1_000_000_000} # 1E9 = almost 32 bits
82             sub INFINITY () { 100**100**100**100 }
83             sub NEG_INFINITY () { -1 * ( 100**100**100**100 ) }
84             sub NAN () { INFINITY - INFINITY }
85              
86             sub SECONDS_PER_DAY () {86400}
87              
88             sub duration_class () {'DateTime::Duration'}
89              
90             my (
91             @MonthLengths,
92             @LeapYearMonthLengths,
93             @QuarterLengths,
94             @LeapYearQuarterLengths,
95             );
96              
97             BEGIN {
98 49     49   21375 @MonthLengths = ( 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 );
99              
100 49         210 @LeapYearMonthLengths = @MonthLengths;
101 49         130 $LeapYearMonthLengths[1]++;
102              
103 49         141 @QuarterLengths = ( 90, 91, 92, 92 );
104              
105 49         173 @LeapYearQuarterLengths = @QuarterLengths;
106 49         190282 $LeapYearQuarterLengths[0]++;
107             }
108              
109             {
110              
111             # I'd rather use Class::Data::Inheritable for this, but there's no
112             # way to add the module-loading behavior to an accessor it
113             # creates, despite what its docs say!
114             my $DefaultLocale;
115              
116             sub DefaultLocale {
117 25445     25445 1 36819 shift;
118              
119 25445 100       48872 if (@_) {
120 50         116 my $lang = shift;
121              
122 50         244 $DefaultLocale = DateTime::Locale->load($lang);
123             }
124              
125 25445         58691 return $DefaultLocale;
126             }
127             }
128             __PACKAGE__->DefaultLocale('en-US');
129              
130             {
131             my $validator = validation_for(
132             name => '_check_new_params',
133             name_is_optional => 1,
134             params => {
135             year => { type => t('Year') },
136             month => {
137             type => t('Month'),
138             default => 1,
139             },
140             day => {
141             type => t('DayOfMonth'),
142             default => 1,
143             },
144             hour => {
145             type => t('Hour'),
146             default => 0,
147             },
148             minute => {
149             type => t('Minute'),
150             default => 0,
151             },
152             second => {
153             type => t('Second'),
154             default => 0,
155             },
156             nanosecond => {
157             type => t('Nanosecond'),
158             default => 0,
159             },
160             locale => {
161             type => t('Locale'),
162             optional => 1,
163             },
164             formatter => {
165             type => t('Formatter'),
166             optional => 1,
167             },
168             time_zone => {
169             type => t('TimeZone'),
170             optional => 1,
171             },
172             },
173             );
174              
175             sub new {
176 48767     48767 1 1491135 my $class = shift;
177 48767         1027214 my %p = $validator->(@_);
178              
179             Carp::croak(
180             "Invalid day of month (day = $p{day} - month = $p{month} - year = $p{year})\n"
181             )
182             if $p{day} > 28
183 48749 100 100     8238960 && $p{day} > $class->_month_length( $p{year}, $p{month} );
184              
185 48747         167449 return $class->_new(%p);
186             }
187             }
188              
189             sub _new {
190 57557     57557   93699 my $class = shift;
191 57557         177298 my %p = @_;
192              
193 57557 100       117983 Carp::croak('Constructor called with reference, we expected a package')
194             if ref $class;
195              
196             # If this method is called from somewhere other than new(), then some of
197             # these defaults may not get applied.
198 57555 50       106500 $p{month} = 1 unless exists $p{month};
199 57555 50       102863 $p{day} = 1 unless exists $p{day};
200 57555 50       98221 $p{hour} = 0 unless exists $p{hour};
201 57555 50       104175 $p{minute} = 0 unless exists $p{minute};
202 57555 50       99934 $p{second} = 0 unless exists $p{second};
203 57555 100       97261 $p{nanosecond} = 0 unless exists $p{nanosecond};
204 57555 100       95463 $p{time_zone} = $class->_default_time_zone unless exists $p{time_zone};
205              
206 57555         113028 my $self = bless {}, $class;
207              
208 57555         167726 $self->_set_locale( $p{locale} );
209              
210             $self->{tz} = (
211             ref $p{time_zone}
212             ? $p{time_zone}
213             : DateTime::TimeZone->new( name => $p{time_zone} )
214 57555 100       235101 );
215              
216 57555         3688082 $self->{local_rd_days} = $class->_ymd2rd( @p{qw( year month day )} );
217              
218             $self->{local_rd_secs}
219 57555         166211 = $class->_time_as_seconds( @p{qw( hour minute second )} );
220              
221 57555         90653 $self->{offset_modifier} = 0;
222              
223 57555         109241 $self->{rd_nanosecs} = $p{nanosecond};
224 57555         103155 $self->{formatter} = $p{formatter};
225              
226             $self->_normalize_nanoseconds(
227             $self->{local_rd_secs},
228             $self->{rd_nanosecs}
229 57555         167116 );
230              
231             # Set this explicitly since it can't be calculated accurately
232             # without knowing our time zone offset, and it's possible that the
233             # offset can't be calculated without having at least a rough guess
234             # of the datetime's year. This year need not be correct, as long
235             # as its equal or greater to the correct number, so we fudge by
236             # adding one to the local year given to the constructor.
237 57555         160605 $self->{utc_year} = $p{year} + 1;
238              
239 57555         153420 $self->_maybe_future_dst_warning( $p{year}, $p{time_zone} );
240              
241 57555         136996 $self->_calc_utc_rd;
242              
243 57552         150652 $self->_handle_offset_modifier( $p{second} );
244              
245 57552         184959 $self->_calc_local_rd;
246              
247 57552 100       136225 if ( $p{second} > 59 ) {
248 49 100 100     129 if (
249             $self->{tz}->is_floating
250             ||
251              
252             # If true, this means that the actual calculated leap
253             # second does not occur in the second given to new()
254             ( $self->{utc_rd_secs} - 86399 < $p{second} - 59 )
255             ) {
256 3         371 Carp::croak("Invalid second value ($p{second})\n");
257             }
258             }
259              
260 57549         220444 return $self;
261             }
262              
263             # Warning: do not use this environment variable unless you have no choice in
264             # the matter.
265             sub _default_time_zone {
266 1330   100 1330   5743 return $ENV{PERL_DATETIME_DEFAULT_TZ} || 'floating';
267             }
268              
269             sub _set_locale {
270 57557     57557   76590 my $self = shift;
271 57557         89967 my $locale = shift;
272              
273 57557 100 100     177852 if ( defined $locale && ref $locale ) {
274 32137         72684 $self->{locale} = $locale;
275             }
276             else {
277             $self->{locale}
278 25420 100       63008 = $locale
279             ? DateTime::Locale->load($locale)
280             : $self->DefaultLocale;
281             }
282              
283 57557         100161 return;
284             }
285              
286             # This method exists for the benefit of internal methods which create
287             # a new object based on the current object, like set() and truncate().
288             sub _new_from_self {
289 200     200   354 my $self = shift;
290 200         534 my %p = @_;
291              
292 200         423 my %old = map { $_ => $self->$_() } qw(
  1800         3874  
293             year month day
294             hour minute second
295             nanosecond
296             locale time_zone
297             );
298 200 100       564 $old{formatter} = $self->formatter
299             if defined $self->formatter;
300              
301 200 100       551 my $method = delete $p{_skip_validation} ? '_new' : 'new';
302              
303 200         965 return ( ref $self )->$method( %old, %p );
304             }
305              
306             sub _handle_offset_modifier {
307 120848     120848   161429 my $self = shift;
308              
309 120848         184503 $self->{offset_modifier} = 0;
310              
311 120848 100       302764 return if $self->{tz}->is_floating;
312              
313 33671         112840 my $second = shift;
314 33671         47466 my $utc_is_valid = shift;
315              
316 33671         47309 my $utc_rd_days = $self->{utc_rd_days};
317              
318 33671 100       78594 my $offset
319             = $utc_is_valid ? $self->offset : $self->_offset_for_local_datetime;
320              
321 33671 100 100     227394 if ( $offset >= 0
    100 100        
322             && $self->{local_rd_secs} >= $offset ) {
323 33399 100 100     149082 if ( $second < 60 && $offset > 0 ) {
    100 66        
      66        
324             $self->{offset_modifier}
325 44         248 = $self->_day_length( $utc_rd_days - 1 ) - SECONDS_PER_DAY;
326              
327 44         118 $self->{local_rd_secs} += $self->{offset_modifier};
328             }
329             elsif (
330             $second == 60
331             && (
332             ( $self->{local_rd_secs} == $offset && $offset > 0 )
333             || ( $offset == 0
334             && $self->{local_rd_secs} > 86399 )
335             )
336             ) {
337 42         140 my $mod
338             = $self->_day_length( $utc_rd_days - 1 ) - SECONDS_PER_DAY;
339              
340 42 100       106 unless ( $mod == 0 ) {
341 41         72 $self->{utc_rd_secs} -= $mod;
342              
343 41         124 $self->_normalize_seconds;
344             }
345             }
346             }
347             elsif ($offset < 0
348             && $self->{local_rd_secs} >= SECONDS_PER_DAY + $offset ) {
349 28 100 66     118 if ( $second < 60 ) {
    100          
350             $self->{offset_modifier}
351 21         76 = $self->_day_length( $utc_rd_days - 1 ) - SECONDS_PER_DAY;
352              
353 21         50 $self->{local_rd_secs} += $self->{offset_modifier};
354             }
355             elsif ($second == 60
356             && $self->{local_rd_secs} == SECONDS_PER_DAY + $offset ) {
357 5         20 my $mod
358             = $self->_day_length( $utc_rd_days - 1 ) - SECONDS_PER_DAY;
359              
360 5 50       19 unless ( $mod == 0 ) {
361 5         9 $self->{utc_rd_secs} -= $mod;
362              
363 5         12 $self->_normalize_seconds;
364             }
365             }
366             }
367             }
368              
369             sub _calc_utc_rd {
370 113218     113218   152749 my $self = shift;
371              
372 113218         191848 delete $self->{utc_c};
373              
374 113218 100 100     297334 if ( $self->{tz}->is_utc || $self->{tz}->is_floating ) {
375 113040         741303 $self->{utc_rd_days} = $self->{local_rd_days};
376 113040         180437 $self->{utc_rd_secs} = $self->{local_rd_secs};
377             }
378             else {
379 178         1680 my $offset = $self->_offset_for_local_datetime;
380              
381 172         23711 $offset += $self->{offset_modifier};
382              
383 172         305 $self->{utc_rd_days} = $self->{local_rd_days};
384 172         350 $self->{utc_rd_secs} = $self->{local_rd_secs} - $offset;
385             }
386              
387             # We account for leap seconds in the new() method and nowhere else
388             # except date math.
389             $self->_normalize_tai_seconds(
390             $self->{utc_rd_days},
391             $self->{utc_rd_secs}
392 113212         363894 );
393             }
394              
395             sub _normalize_seconds {
396 7623     7623   11210 my $self = shift;
397              
398 7623 100 100     28378 return if $self->{utc_rd_secs} >= 0 && $self->{utc_rd_secs} <= 86399;
399              
400 78 100       219 if ( $self->{tz}->is_floating ) {
401             $self->_normalize_tai_seconds(
402             $self->{utc_rd_days},
403             $self->{utc_rd_secs}
404 3         20 );
405             }
406             else {
407             $self->_normalize_leap_seconds(
408             $self->{utc_rd_days},
409             $self->{utc_rd_secs}
410 75         5080 );
411             }
412             }
413              
414             sub _calc_local_rd {
415 57806     57806   81209 my $self = shift;
416              
417 57806         79911 delete $self->{local_c};
418              
419             # We must short circuit for UTC times or else we could end up with
420             # loops between DateTime.pm and DateTime::TimeZone
421 57806 100 100     113768 if ( $self->{tz}->is_utc || $self->{tz}->is_floating ) {
422 57548         292791 $self->{local_rd_days} = $self->{utc_rd_days};
423 57548         96092 $self->{local_rd_secs} = $self->{utc_rd_secs};
424             }
425             else {
426 258         2015 my $offset = $self->offset;
427              
428 258         13959 $self->{local_rd_days} = $self->{utc_rd_days};
429 258         481 $self->{local_rd_secs} = $self->{utc_rd_secs} + $offset;
430              
431             # intentionally ignore leap seconds here
432             $self->_normalize_tai_seconds(
433             $self->{local_rd_days},
434             $self->{local_rd_secs}
435 258         859 );
436              
437 258         484 $self->{local_rd_secs} += $self->{offset_modifier};
438             }
439              
440 57806         125767 $self->_calc_local_components;
441             }
442              
443             sub _calc_local_components {
444 57806     57806   83090 my $self = shift;
445              
446 57806         248580 @{ $self->{local_c} }{
447             qw( year month day day_of_week
448             day_of_year quarter day_of_quarter)
449             }
450 57806         181172 = $self->_rd2ymd( $self->{local_rd_days}, 1 );
451              
452 57806         183545 @{ $self->{local_c} }{qw( hour minute second )}
453             = $self->_seconds_as_components(
454             $self->{local_rd_secs},
455             $self->{utc_rd_secs}, $self->{offset_modifier}
456 57806         165510 );
457             }
458              
459             {
460             my $named_validator = validation_for(
461             name => '_check_named_from_epoch_params',
462             name_is_optional => 1,
463             params => {
464             epoch => { type => t('Num') },
465             formatter => {
466             type => t('Formatter'),
467             optional => 1
468             },
469             locale => {
470             type => t('Locale'),
471             optional => 1
472             },
473             time_zone => {
474             type => t('TimeZone'),
475             optional => 1
476             },
477             },
478             );
479              
480             my $one_param_validator = validation_for(
481             name => '_check_one_from_epoch_param',
482             name_is_optional => 1,
483             params => [ { type => t('Num') } ],
484             );
485              
486             sub from_epoch {
487 59     59 1 21757 my $class = shift;
488 59         117 my %p;
489 59 100 66     286 if ( @_ == 1 && !is_HashRef( $_[0] ) ) {
490 3         138 ( $p{epoch} ) = $one_param_validator->(@_);
491             }
492             else {
493 56         1508 %p = $named_validator->(@_);
494             }
495              
496 56         3001 my %args;
497              
498             # This does two things. First, if given a negative non-integer epoch,
499             # it will round the epoch _down_ to the next second and then adjust
500             # the nanoseconds to be positive. In other words, -0.5 corresponds to
501             # a second of -1 and a nanosecond value of 500,000. Before this code
502             # was implemented our handling of negative non-integer epochs was
503             # quite broken, and would end up rounding some values up, so that -0.5
504             # become 0.5 (which is obviously wrong!).
505             #
506             # Second, it rounds any decimal values to the nearest microsecond
507             # (1E6). Here's what Christian Hansen, who wrote this patch, says:
508             #
509             # Perl is typically compiled with NV as a double. A double with a
510             # significand precision of 53 bits can only represent a nanosecond
511             # epoch without loss of precision if the duration from zero epoch
512             # is less than ≈ ±104 days. With microseconds the duration is
513             # ±104,000 days, which is ≈ ±285 years.
514 56 100       388 if ( int $p{epoch} != $p{epoch} ) {
515 8         29 my ( $floor, $nano, $second );
516              
517 8         37 $floor = $nano = fmod( $p{epoch}, 1.0 );
518 8         36 $second = floor( $p{epoch} - $floor );
519 8 100       33 if ( $nano < 0 ) {
520 2         5 $nano += 1;
521             }
522 8         25 $p{epoch} = $second + floor( $floor - $nano );
523 8         28 $args{nanosecond} = floor( $nano * 1E6 + 0.5 ) * 1E3;
524             }
525              
526             # Note, for very large negative values this may give a
527             # blatantly wrong answer.
528             @args{qw( second minute hour day month year )}
529 56         811 = ( gmtime( $p{epoch} ) )[ 0 .. 5 ];
530 56         202 $args{year} += 1900;
531 56         128 $args{month}++;
532              
533 56         283 my $self = $class->_new( %p, %args, time_zone => 'UTC' );
534              
535 54         209 $self->_maybe_future_dst_warning( $self->year, $p{time_zone} );
536              
537 54 100       206 $self->set_time_zone( $p{time_zone} ) if exists $p{time_zone};
538              
539 54         301 return $self;
540             }
541             }
542              
543             sub now {
544 31     31 1 17375 my $class = shift;
545 31         132 return $class->from_epoch( epoch => $class->_core_time, @_ );
546             }
547              
548             sub _maybe_future_dst_warning {
549 57609     57609   76190 shift;
550 57609         79570 my $year = shift;
551 57609         76482 my $tz = shift;
552              
553 57609 100 66     150366 return unless $year >= 5000 && $tz;
554              
555 10 50       34 my $tz_name = ref $tz ? $tz->name : $tz;
556 10 100 100     49 return if $tz_name eq 'floating' || $tz_name eq 'UTC';
557              
558 5         624 warnings::warnif(
559             "You are creating a DateTime object with a far future year ($year) and a time zone ($tz_name)."
560             . ' If the time zone you specified has future DST changes this will be very slow.'
561             );
562             }
563              
564             # use scalar time in case someone's loaded Time::Piece
565             sub _core_time {
566 30     30   137 return scalar time;
567             }
568              
569 3     3 1 504 sub today { shift->now(@_)->truncate( to => 'day' ) }
570              
571             {
572             my $validator = validation_for(
573             name => '_check_from_object_params',
574             name_is_optional => 1,
575             params => {
576             object => { type => t('ConvertibleObject') },
577             locale => {
578             type => t('Locale'),
579             optional => 1,
580             },
581             formatter => {
582             type => t('Formatter'),
583             optional => 1,
584             },
585             },
586             );
587              
588             sub from_object {
589 31947     31947 1 52447 my $class = shift;
590 31947         707897 my %p = $validator->(@_);
591              
592 31947         3185772 my $object = delete $p{object};
593              
594 31947 100       140537 if ( $object->isa('DateTime::Infinite') ) {
595 2         10 return $object->clone;
596             }
597              
598 31945         67036 my ( $rd_days, $rd_secs, $rd_nanosecs ) = $object->utc_rd_values;
599              
600             # A kludge because until all calendars are updated to return all
601             # three values, $rd_nanosecs could be undef
602 31945   100     141596 $rd_nanosecs ||= 0;
603              
604             # This is a big hack to let _seconds_as_components operate naively
605             # on the given value. If the object _is_ on a leap second, we'll
606             # add that to the generated seconds value later.
607 31945         41722 my $leap_seconds = 0;
608 31945 100 100     111423 if ( $object->can('time_zone')
      100        
      66        
609             && !$object->time_zone->is_floating
610             && $rd_secs > 86399
611             && $rd_secs <= $class->_day_length($rd_days) ) {
612 6         61 $leap_seconds = $rd_secs - 86399;
613 6         14 $rd_secs -= $leap_seconds;
614             }
615              
616 31945         144165 my %args;
617 31945         122164 @args{qw( year month day )} = $class->_rd2ymd($rd_days);
618 31945         103238 @args{qw( hour minute second )}
619             = $class->_seconds_as_components($rd_secs);
620 31945         55852 $args{nanosecond} = $rd_nanosecs;
621              
622 31945         45363 $args{second} += $leap_seconds;
623              
624 31945         104207 my $new = $class->new( %p, %args, time_zone => 'UTC' );
625              
626 31945 100       130087 if ( $object->can('time_zone') ) {
627 31943         66668 $new->set_time_zone( $object->time_zone );
628             }
629             else {
630 2         9 $new->set_time_zone( $class->_default_time_zone );
631             }
632              
633 31945         101394 return $new;
634             }
635             }
636              
637             {
638             my $validator = validation_for(
639             name => '_check_last_day_of_month_params',
640             name_is_optional => 1,
641             params => {
642             year => { type => t('Year') },
643             month => { type => t('Month') },
644             day => {
645             type => t('DayOfMonth'),
646             default => 1,
647             },
648             hour => {
649             type => t('Hour'),
650             default => 0,
651             },
652             minute => {
653             type => t('Minute'),
654             default => 0,
655             },
656             second => {
657             type => t('Second'),
658             default => 0,
659             },
660             nanosecond => {
661             type => t('Nanosecond'),
662             default => 0,
663             },
664             locale => {
665             type => t('Locale'),
666             optional => 1,
667             },
668             formatter => {
669             type => t('Formatter'),
670             optional => 1,
671             },
672             time_zone => {
673             type => t('TimeZone'),
674             optional => 1,
675             },
676             },
677             );
678              
679             sub last_day_of_month {
680 7464     7464 1 828570 my $class = shift;
681 7464         159440 my %p = $validator->(@_);
682              
683 7462         997369 my $day = $class->_month_length( $p{year}, $p{month} );
684              
685 7462         24575 return $class->_new( %p, day => $day );
686             }
687             }
688              
689             sub _month_length {
690             return (
691 40098 100   40098   208432 $_[0]->_is_leap_year( $_[1] )
692             ? $LeapYearMonthLengths[ $_[2] - 1 ]
693             : $MonthLengths[ $_[2] - 1 ]
694             );
695             }
696              
697             {
698             my $validator = validation_for(
699             name => '_check_from_day_of_year_params',
700             name_is_optional => 1,
701             params => {
702             year => { type => t('Year') },
703             day_of_year => { type => t('DayOfYear') },
704             hour => {
705             type => t('Hour'),
706             default => 0,
707             },
708             minute => {
709             type => t('Minute'),
710             default => 0,
711             },
712             second => {
713             type => t('Second'),
714             default => 0,
715             },
716             nanosecond => {
717             type => t('Nanosecond'),
718             default => 0,
719             },
720             locale => {
721             type => t('Locale'),
722             optional => 1,
723             },
724             formatter => {
725             type => t('Formatter'),
726             optional => 1,
727             },
728             time_zone => {
729             type => t('TimeZone'),
730             optional => 1,
731             },
732             },
733             );
734              
735             sub from_day_of_year {
736 1124     1124 1 22636 my $class = shift;
737 1124         27537 my %p = $validator->(@_);
738              
739             Carp::croak("$p{year} is not a leap year.\n")
740 1124 100 100     97061 if $p{day_of_year} == 366 && !$class->_is_leap_year( $p{year} );
741              
742 1123         1653 my $month = 1;
743 1123         2140 my $day = delete $p{day_of_year};
744              
745 1123 100       2652 if ( $day > 31 ) {
746 1028         2924 my $length = $class->_month_length( $p{year}, $month );
747              
748 1028         2238 while ( $day > $length ) {
749 6207         7398 $day -= $length;
750 6207         6866 $month++;
751 6207         10145 $length = $class->_month_length( $p{year}, $month );
752             }
753             }
754              
755 1123         3420 return $class->_new(
756             %p,
757             month => $month,
758             day => $day,
759             );
760             }
761             }
762              
763 205     205 1 902 sub formatter { $_[0]->{formatter} }
764              
765 32057     32057 1 108563 sub clone { bless { %{ $_[0] } }, ref $_[0] }
  32057         249849  
766              
767             sub year {
768 1745 50   1745 1 5448 Carp::carp('year() is a read-only accessor') if @_ > 1;
769 1745         9874 return $_[0]->{local_c}{year};
770             }
771              
772             sub ce_year {
773             $_[0]->{local_c}{year} <= 0
774             ? $_[0]->{local_c}{year} - 1
775 23 100   23 1 902 : $_[0]->{local_c}{year};
776             }
777              
778 2     2 1 12 sub era_name { $_[0]->{locale}->era_wide->[ $_[0]->_era_index ] }
779              
780 10     10 1 46 sub era_abbr { $_[0]->{locale}->era_abbreviated->[ $_[0]->_era_index ] }
781              
782             # deprecated
783             *era = \&era_abbr;
784              
785 13 100   13   136 sub _era_index { $_[0]->{local_c}{year} <= 0 ? 0 : 1 }
786              
787 4 100   4 1 9 sub christian_era { $_[0]->ce_year > 0 ? 'AD' : 'BC' }
788 4 100   4 1 11 sub secular_era { $_[0]->ce_year > 0 ? 'CE' : 'BCE' }
789              
790 2     2 1 8 sub year_with_era { ( abs $_[0]->ce_year ) . $_[0]->era_abbr }
791 2     2 1 6 sub year_with_christian_era { ( abs $_[0]->ce_year ) . $_[0]->christian_era }
792 2     2 1 9 sub year_with_secular_era { ( abs $_[0]->ce_year ) . $_[0]->secular_era }
793              
794             sub month {
795 8616 50   8616 1 44348 Carp::carp('month() is a read-only accessor') if @_ > 1;
796 8616         21376 return $_[0]->{local_c}{month};
797             }
798             *mon = \&month;
799              
800 19     19 0 199 sub month_0 { $_[0]->{local_c}{month} - 1 }
801             *mon_0 = \&month_0;
802              
803 6     6 1 45 sub month_name { $_[0]->{locale}->month_format_wide->[ $_[0]->month_0 ] }
804              
805             sub month_abbr {
806 8     8 1 43 $_[0]->{locale}->month_format_abbreviated->[ $_[0]->month_0 ];
807             }
808              
809             sub day_of_month {
810 15907 50   15907 0 54743 Carp::carp('day_of_month() is a read-only accessor') if @_ > 1;
811 15907         74316 $_[0]->{local_c}{day};
812             }
813             *day = \&day_of_month;
814             *mday = \&day_of_month;
815              
816 49     49 1 28057 sub weekday_of_month { use integer; ( ( $_[0]->day - 1 ) / 7 ) + 1 }
  49     4   1304  
  49         364  
  4         21  
817              
818 30     30 1 983 sub quarter { $_[0]->{local_c}{quarter} }
819              
820             sub quarter_name {
821 2     2 1 17 $_[0]->{locale}->quarter_format_wide->[ $_[0]->quarter_0 ];
822             }
823              
824             sub quarter_abbr {
825 2     2 1 15 $_[0]->{locale}->quarter_format_abbreviated->[ $_[0]->quarter_0 ];
826             }
827              
828 6     6 0 64 sub quarter_0 { $_[0]->{local_c}{quarter} - 1 }
829              
830 4     4 0 23 sub day_of_month_0 { $_[0]->{local_c}{day} - 1 }
831             *day_0 = \&day_of_month_0;
832             *mday_0 = \&day_of_month_0;
833              
834 32710     32710 1 134435 sub day_of_week { $_[0]->{local_c}{day_of_week} }
835             *wday = \&day_of_week;
836             *dow = \&day_of_week;
837              
838 23     23 0 207 sub day_of_week_0 { $_[0]->{local_c}{day_of_week} - 1 }
839             *wday_0 = \&day_of_week_0;
840             *dow_0 = \&day_of_week_0;
841              
842             sub local_day_of_week {
843 4     4 1 7 my $self = shift;
844             return 1
845 4         9 + ( $self->day_of_week - $self->{locale}->first_day_of_week ) % 7;
846             }
847              
848 7     7 1 717 sub day_name { $_[0]->{locale}->day_format_wide->[ $_[0]->day_of_week_0 ] }
849              
850             sub day_abbr {
851 8     8 1 40 $_[0]->{locale}->day_format_abbreviated->[ $_[0]->day_of_week_0 ];
852             }
853              
854 18     18 1 68 sub day_of_quarter { $_[0]->{local_c}{day_of_quarter} }
855             *doq = \&day_of_quarter;
856              
857 2     2 0 7 sub day_of_quarter_0 { $_[0]->day_of_quarter - 1 }
858             *doq_0 = \&day_of_quarter_0;
859              
860 79     79 1 270 sub day_of_year { $_[0]->{local_c}{day_of_year} }
861             *doy = \&day_of_year;
862              
863 3     3 0 15 sub day_of_year_0 { $_[0]->{local_c}{day_of_year} - 1 }
864             *doy_0 = \&day_of_year_0;
865              
866             sub am_or_pm {
867 25 100   25 1 117 $_[0]->{locale}->am_pm_abbreviated->[ $_[0]->hour < 12 ? 0 : 1 ];
868             }
869              
870             sub ymd {
871 828     828 1 2025 my ( $self, $sep ) = @_;
872 828 100       1927 $sep = '-' unless defined $sep;
873              
874             return sprintf(
875             '%0.4d%s%0.2d%s%0.2d',
876             $self->year, $sep,
877             $self->{local_c}{month}, $sep,
878             $self->{local_c}{day}
879 828         1774 );
880             }
881 522     522   13345 *date = sub { shift->ymd(@_) };
882              
883             sub mdy {
884 4     4 1 11 my ( $self, $sep ) = @_;
885 4 100       14 $sep = '-' unless defined $sep;
886              
887             return sprintf(
888             '%0.2d%s%0.2d%s%0.4d',
889             $self->{local_c}{month}, $sep,
890 4         13 $self->{local_c}{day}, $sep,
891             $self->year
892             );
893             }
894              
895             sub dmy {
896 4     4 1 13 my ( $self, $sep ) = @_;
897 4 100       12 $sep = '-' unless defined $sep;
898              
899             return sprintf(
900             '%0.2d%s%0.2d%s%0.4d',
901             $self->{local_c}{day}, $sep,
902 4         13 $self->{local_c}{month}, $sep,
903             $self->year
904             );
905             }
906              
907             sub hour {
908 551 50   551 1 6593 Carp::carp('hour() is a read-only accessor') if @_ > 1;
909 551         1600 return $_[0]->{local_c}{hour};
910             }
911 7 100   7 1 792 sub hour_1 { $_[0]->{local_c}{hour} == 0 ? 24 : $_[0]->{local_c}{hour} }
912              
913 33 100   33 1 124 sub hour_12 { my $h = $_[0]->hour % 12; return $h ? $h : 12 }
  33         197  
914 5     5 1 17 sub hour_12_0 { $_[0]->hour % 12 }
915              
916             sub minute {
917 501 50   501 1 6357 Carp::carp('minute() is a read-only accessor') if @_ > 1;
918 501         1368 return $_[0]->{local_c}{minute};
919             }
920             *min = \&minute;
921              
922             sub second {
923 63801 50   63801 1 143098 Carp::carp('second() is a read-only accessor') if @_ > 1;
924 63801         160733 return $_[0]->{local_c}{second};
925             }
926             *sec = \&second;
927              
928 3     3 1 753 sub fractional_second { $_[0]->second + $_[0]->nanosecond / MAX_NANOSECONDS }
929              
930             sub nanosecond {
931 468 50   468 1 6325 Carp::carp('nanosecond() is a read-only accessor') if @_ > 1;
932 468         1109 return $_[0]->{rd_nanosecs};
933             }
934              
935 10     10 1 1637 sub millisecond { floor( $_[0]->{rd_nanosecs} / 1000000 ) }
936              
937 9     9 1 1633 sub microsecond { floor( $_[0]->{rd_nanosecs} / 1000 ) }
938              
939             sub leap_seconds {
940 3     3 1 14 my $self = shift;
941              
942 3 100       9 return 0 if $self->{tz}->is_floating;
943              
944 2         17 return $self->_accumulated_leap_seconds( $self->{utc_rd_days} );
945             }
946              
947             sub stringify {
948 36     36 1 118 my $self = shift;
949              
950 36 100       112 return $self->iso8601 unless $self->{formatter};
951 5         17 return $self->{formatter}->format_datetime($self);
952             }
953              
954             sub hms {
955 168     168 1 319 my ( $self, $sep ) = @_;
956 168 100       335 $sep = ':' unless defined $sep;
957              
958             return sprintf(
959             '%0.2d%s%0.2d%s%0.2d',
960             $self->{local_c}{hour}, $sep,
961             $self->{local_c}{minute}, $sep,
962             $self->{local_c}{second}
963 168         1492 );
964             }
965              
966             # don't want to override CORE::time()
967 4     4   789 *DateTime::time = sub { shift->hms(@_) };
968              
969 52     52 0 911 sub iso8601 { $_[0]->datetime('T') }
970              
971             sub rfc3339 {
972 4     4 1 26 my $self = shift;
973              
974             return $self->datetime('T')
975 4 100       11 if $self->{tz}->is_floating;
976              
977 3         18 my $secs = $self->offset;
978 3 100       62 my $offset
979             = $secs
980             ? DateTime::TimeZone->offset_as_string( $secs, q{:} )
981             : 'Z';
982              
983 3         164 return $self->datetime('T') . $offset;
984             }
985              
986             sub datetime {
987 163     163 1 2819 my ( $self, $sep ) = @_;
988 163 100       398 $sep = 'T' unless defined $sep;
989 163         387 return join $sep, $self->ymd('-'), $self->hms(':');
990             }
991              
992 2     2 1 9 sub is_leap_year { $_[0]->_is_leap_year( $_[0]->year ) }
993              
994             sub month_length {
995 3     3 1 18 $_[0]->_month_length( $_[0]->year, $_[0]->month );
996             }
997              
998             sub quarter_length {
999             return (
1000 15 100   15 1 41 $_[0]->_is_leap_year( $_[0]->year )
1001             ? $LeapYearQuarterLengths[ $_[0]->quarter - 1 ]
1002             : $QuarterLengths[ $_[0]->quarter - 1 ]
1003             );
1004             }
1005              
1006             sub year_length {
1007 5 100   5 1 13 $_[0]->_is_leap_year( $_[0]->year ) ? 366 : 365;
1008             }
1009              
1010             sub is_last_day_of_month {
1011 5     5 1 23 $_[0]->day == $_[0]->_month_length( $_[0]->year, $_[0]->month );
1012             }
1013              
1014             sub is_last_day_of_quarter {
1015 6     6 1 28 $_[0]->day_of_quarter == $_[0]->quarter_length;
1016             }
1017              
1018             sub is_last_day_of_year {
1019 3     3 1 14 $_[0]->day_of_year == $_[0]->year_length;
1020             }
1021              
1022             sub week {
1023 45     45 1 925 my $self = shift;
1024              
1025 45   66     189 $self->{utc_c}{week_year} ||= $self->_week_values;
1026              
1027 45         68 return @{ $self->{utc_c}{week_year} }[ 0, 1 ];
  45         229  
1028             }
1029              
1030             # This algorithm comes from
1031             # https://en.wikipedia.org/wiki/ISO_week_date#Calculating_the_week_number_of_a_given_date
1032             sub _week_values {
1033 31     31   50 my $self = shift;
1034              
1035 31         70 my $week
1036             = int( ( ( $self->day_of_year - $self->day_of_week ) + 10 ) / 7 );
1037              
1038 31         68 my $year = $self->year;
1039 31 100 100     110 if ( $week == 0 ) {
    100          
1040 4         6 $year--;
1041 4         9 return [ $year, $self->_weeks_in_year($year) ];
1042             }
1043             elsif ( $week == 53 && $self->_weeks_in_year($year) == 52 ) {
1044 5         29 return [ $year + 1, 1 ];
1045             }
1046              
1047 22         87 return [ $year, $week ];
1048             }
1049              
1050             sub _weeks_in_year {
1051 11     11   19 my $self = shift;
1052 11         13 my $year = shift;
1053              
1054 11         27 my $dow = $self->_ymd2rd( $year, 1, 1 ) % 7;
1055              
1056             # Years starting with a Thursday and leap years starting with a Wednesday
1057             # have 53 weeks.
1058 11 100 100     73 return ( $dow == 4 || ( $dow == 3 && $self->_is_leap_year($year) ) )
1059             ? 53
1060             : 52;
1061             }
1062              
1063 9     9 1 772 sub week_year { ( $_[0]->week )[0] }
1064 8     8 1 827 sub week_number { ( $_[0]->week )[1] }
1065              
1066             # ISO says that the first week of a year is the first week containing
1067             # a Thursday. Extending that says that the first week of the month is
1068             # the first week containing a Thursday. ICU agrees.
1069             sub week_of_month {
1070 4     4 1 11 my $self = shift;
1071 4         13 my $thu = $self->day + 4 - $self->day_of_week;
1072 4         24 return int( ( $thu + 6 ) / 7 );
1073             }
1074              
1075             sub time_zone {
1076 82348 50   82348 1 162308 Carp::carp('time_zone() is a read-only accessor') if @_ > 1;
1077 82348         225421 return $_[0]->{tz};
1078             }
1079              
1080 434     434 1 2110 sub offset { $_[0]->{tz}->offset_for_datetime( $_[0] ) }
1081              
1082             sub _offset_for_local_datetime {
1083 33688     33688   87419 $_[0]->{tz}->offset_for_local_datetime( $_[0] );
1084             }
1085              
1086 71     71 1 1753 sub is_dst { $_[0]->{tz}->is_dst_for_datetime( $_[0] ) }
1087              
1088 3     3 1 17 sub time_zone_long_name { $_[0]->{tz}->name }
1089 5     5 1 702 sub time_zone_short_name { $_[0]->{tz}->short_name_for_datetime( $_[0] ) }
1090              
1091             sub locale {
1092 213 50   213 1 3525 Carp::carp('locale() is a read-only accessor') if @_ > 1;
1093 213         577 return $_[0]->{locale};
1094             }
1095              
1096             sub utc_rd_values {
1097 50010     50010 1 80059 @{ $_[0] }{ 'utc_rd_days', 'utc_rd_secs', 'rd_nanosecs' };
  50010         169585  
1098             }
1099              
1100             sub local_rd_values {
1101 14     14 1 4193 @{ $_[0] }{ 'local_rd_days', 'local_rd_secs', 'rd_nanosecs' };
  14         64  
1102             }
1103              
1104             # NOTE: no nanoseconds, no leap seconds
1105             sub utc_rd_as_seconds {
1106 31741     31741 1 510846 ( $_[0]->{utc_rd_days} * SECONDS_PER_DAY ) + $_[0]->{utc_rd_secs};
1107             }
1108              
1109             # NOTE: no nanoseconds, no leap seconds
1110             sub local_rd_as_seconds {
1111 255     255 0 3751 ( $_[0]->{local_rd_days} * SECONDS_PER_DAY ) + $_[0]->{local_rd_secs};
1112             }
1113              
1114             # RD 1 is MJD 678,576 - a simple offset
1115             sub mjd {
1116 28     28 1 800 my $self = shift;
1117              
1118 28         52 my $mjd = $self->{utc_rd_days} - 678_576;
1119              
1120 28         91 my $day_length = $self->_day_length( $self->{utc_rd_days} );
1121              
1122             return ( $mjd
1123             + ( $self->{utc_rd_secs} / $day_length )
1124 28         246 + ( $self->{rd_nanosecs} / $day_length / MAX_NANOSECONDS ) );
1125             }
1126              
1127 16     16 1 791 sub jd { $_[0]->mjd + 2_400_000.5 }
1128              
1129             {
1130             my %strftime_patterns = (
1131             'a' => sub { $_[0]->day_abbr },
1132             'A' => sub { $_[0]->day_name },
1133             'b' => sub { $_[0]->month_abbr },
1134             'B' => sub { $_[0]->month_name },
1135             'c' => sub {
1136             $_[0]->format_cldr( $_[0]->{locale}->datetime_format_default );
1137             },
1138             'C' => sub { int( $_[0]->year / 100 ) },
1139             'd' => sub { sprintf( '%02d', $_[0]->day_of_month ) },
1140             'D' => sub { $_[0]->strftime('%m/%d/%y') },
1141             'e' => sub { sprintf( '%2d', $_[0]->day_of_month ) },
1142             'F' => sub { $_[0]->strftime('%Y-%m-%d') },
1143             'g' => sub { substr( $_[0]->week_year, -2 ) },
1144             'G' => sub { $_[0]->week_year },
1145             'H' => sub { sprintf( '%02d', $_[0]->hour ) },
1146             'I' => sub { sprintf( '%02d', $_[0]->hour_12 ) },
1147             'j' => sub { sprintf( '%03d', $_[0]->day_of_year ) },
1148             'k' => sub { sprintf( '%2d', $_[0]->hour ) },
1149             'l' => sub { sprintf( '%2d', $_[0]->hour_12 ) },
1150             'm' => sub { sprintf( '%02d', $_[0]->month ) },
1151             'M' => sub { sprintf( '%02d', $_[0]->minute ) },
1152             'n' => sub {"\n"}, # should this be OS-sensitive?
1153             'N' => \&_format_nanosecs,
1154             'p' => sub { $_[0]->am_or_pm },
1155             'P' => sub { lc $_[0]->am_or_pm },
1156             'r' => sub { $_[0]->strftime('%I:%M:%S %p') },
1157             'R' => sub { $_[0]->strftime('%H:%M') },
1158             's' => sub { $_[0]->epoch },
1159             'S' => sub { sprintf( '%02d', $_[0]->second ) },
1160             't' => sub {"\t"},
1161             'T' => sub { $_[0]->strftime('%H:%M:%S') },
1162             'u' => sub { $_[0]->day_of_week },
1163             'U' => sub {
1164             my $sun = $_[0]->day_of_year - ( $_[0]->day_of_week + 7 ) % 7;
1165             return sprintf( '%02d', int( ( $sun + 6 ) / 7 ) );
1166             },
1167             'V' => sub { sprintf( '%02d', $_[0]->week_number ) },
1168             'w' => sub {
1169             my $dow = $_[0]->day_of_week;
1170             return $dow % 7;
1171             },
1172             'W' => sub {
1173             my $mon = $_[0]->day_of_year - ( $_[0]->day_of_week + 6 ) % 7;
1174             return sprintf( '%02d', int( ( $mon + 6 ) / 7 ) );
1175             },
1176             'x' => sub {
1177             $_[0]->format_cldr( $_[0]->{locale}->date_format_default );
1178             },
1179             'X' => sub {
1180             $_[0]->format_cldr( $_[0]->{locale}->time_format_default );
1181             },
1182             'y' => sub { sprintf( '%02d', substr( $_[0]->year, -2 ) ) },
1183             'Y' => sub { return $_[0]->year },
1184             'z' => sub { DateTime::TimeZone->offset_as_string( $_[0]->offset ) },
1185             'Z' => sub { $_[0]->{tz}->short_name_for_datetime( $_[0] ) },
1186             '%' => sub {'%'},
1187             );
1188              
1189             $strftime_patterns{h} = $strftime_patterns{b};
1190              
1191             sub strftime {
1192 186     186 1 110384 my $self = shift;
1193              
1194             # make a copy or caller's scalars get munged
1195 186         386 my @patterns = @_;
1196              
1197 186         243 my @r;
1198 186         318 for my $p (@patterns) {
1199 187         1409 $p =~ s/
1200             (?:
1201             %\{(\w+)\} # method name like %{day_name}
1202             |
1203             %([%a-zA-Z]) # single character specifier like %d
1204             |
1205             %(\d+)N # special case for %N
1206             )
1207             /
1208             ( $1
1209             ? ( $self->can($1) ? $self->$1() : "\%{$1}" )
1210             : $2
1211             ? ( $strftime_patterns{$2} ? $strftime_patterns{$2}->($self) : "\%$2" )
1212             : $3
1213 270 100       1715 ? $strftime_patterns{N}->($self, $3)
    100          
    50          
    100          
    100          
1214             : '' # this won't happen
1215             )
1216             /sgex;
1217              
1218 187 100       1558 return $p unless wantarray;
1219              
1220 2         5 push @r, $p;
1221             }
1222              
1223 1         5 return @r;
1224             }
1225             }
1226              
1227             {
1228              
1229             # It's an array because the order in which the regexes are checked
1230             # is important. These patterns are similar to the ones Java uses,
1231             # but not quite the same. See
1232             # http://www.unicode.org/reports/tr35/tr35-9.html#Date_Format_Patterns.
1233             my @patterns = (
1234             qr/GGGGG/ =>
1235             sub { $_[0]->{locale}->era_narrow->[ $_[0]->_era_index ] },
1236             qr/GGGG/ => 'era_name',
1237             qr/G{1,3}/ => 'era_abbr',
1238              
1239             qr/(y{3,5})/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->year ) },
1240              
1241             # yy is a weird special case, where it must be exactly 2 digits
1242             qr/yy/ => sub {
1243             my $year = $_[0]->year;
1244             my $y2 = length $year > 2 ? substr( $year, -2, 2 ) : $year;
1245             $y2 *= -1 if $year < 0;
1246             $_[0]->_zero_padded_number( 'yy', $y2 );
1247             },
1248             qr/y/ => 'year',
1249             qr/(u+)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->year ) },
1250             qr/(Y+)/ =>
1251             sub { $_[0]->_zero_padded_number( $1, $_[0]->week_year ) },
1252              
1253             qr/QQQQ/ => 'quarter_name',
1254             qr/QQQ/ => 'quarter_abbr',
1255             qr/(QQ?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->quarter ) },
1256              
1257             qr/qqqq/ => sub {
1258             $_[0]->{locale}->quarter_stand_alone_wide->[ $_[0]->quarter_0 ];
1259             },
1260             qr/qqq/ => sub {
1261             $_[0]->{locale}
1262             ->quarter_stand_alone_abbreviated->[ $_[0]->quarter_0 ];
1263             },
1264             qr/(qq?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->quarter ) },
1265              
1266             qr/MMMMM/ =>
1267             sub { $_[0]->{locale}->month_format_narrow->[ $_[0]->month_0 ] },
1268             qr/MMMM/ => 'month_name',
1269             qr/MMM/ => 'month_abbr',
1270             qr/(MM?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->month ) },
1271              
1272             qr/LLLLL/ => sub {
1273             $_[0]->{locale}->month_stand_alone_narrow->[ $_[0]->month_0 ];
1274             },
1275             qr/LLLL/ => sub {
1276             $_[0]->{locale}->month_stand_alone_wide->[ $_[0]->month_0 ];
1277             },
1278             qr/LLL/ => sub {
1279             $_[0]->{locale}
1280             ->month_stand_alone_abbreviated->[ $_[0]->month_0 ];
1281             },
1282             qr/(LL?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->month ) },
1283              
1284             qr/(ww?)/ =>
1285             sub { $_[0]->_zero_padded_number( $1, $_[0]->week_number ) },
1286             qr/W/ => 'week_of_month',
1287              
1288             qr/(dd?)/ =>
1289             sub { $_[0]->_zero_padded_number( $1, $_[0]->day_of_month ) },
1290             qr/(D{1,3})/ =>
1291             sub { $_[0]->_zero_padded_number( $1, $_[0]->day_of_year ) },
1292              
1293             qr/F/ => 'weekday_of_month',
1294             qr/(g+)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->mjd ) },
1295              
1296             qr/EEEEE/ => sub {
1297             $_[0]->{locale}->day_format_narrow->[ $_[0]->day_of_week_0 ];
1298             },
1299             qr/EEEE/ => 'day_name',
1300             qr/E{1,3}/ => 'day_abbr',
1301              
1302             qr/eeeee/ => sub {
1303             $_[0]->{locale}->day_format_narrow->[ $_[0]->day_of_week_0 ];
1304             },
1305             qr/eeee/ => 'day_name',
1306             qr/eee/ => 'day_abbr',
1307             qr/(ee?)/ => sub {
1308             $_[0]->_zero_padded_number( $1, $_[0]->local_day_of_week );
1309             },
1310              
1311             qr/ccccc/ => sub {
1312             $_[0]->{locale}->day_stand_alone_narrow->[ $_[0]->day_of_week_0 ];
1313             },
1314             qr/cccc/ => sub {
1315             $_[0]->{locale}->day_stand_alone_wide->[ $_[0]->day_of_week_0 ];
1316             },
1317             qr/ccc/ => sub {
1318             $_[0]->{locale}
1319             ->day_stand_alone_abbreviated->[ $_[0]->day_of_week_0 ];
1320             },
1321             qr/(cc?)/ =>
1322             sub { $_[0]->_zero_padded_number( $1, $_[0]->day_of_week ) },
1323              
1324             qr/a/ => 'am_or_pm',
1325              
1326             qr/(hh?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->hour_12 ) },
1327             qr/(HH?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->hour ) },
1328             qr/(KK?)/ =>
1329             sub { $_[0]->_zero_padded_number( $1, $_[0]->hour_12_0 ) },
1330             qr/(kk?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->hour_1 ) },
1331             qr/(jj?)/ => sub {
1332             my $h
1333             = $_[0]->{locale}->prefers_24_hour_time
1334             ? $_[0]->hour
1335             : $_[0]->hour_12;
1336             $_[0]->_zero_padded_number( $1, $h );
1337             },
1338              
1339             qr/(mm?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->minute ) },
1340              
1341             qr/(ss?)/ => sub { $_[0]->_zero_padded_number( $1, $_[0]->second ) },
1342              
1343             # The LDML spec is not 100% clear on how to truncate this field, but
1344             # this way seems as good as anything.
1345             qr/(S+)/ => sub { $_[0]->_format_nanosecs( length($1) ) },
1346             qr/A+/ =>
1347             sub { ( $_[0]->{local_rd_secs} * 1000 ) + $_[0]->millisecond },
1348              
1349             qr/zzzz/ => 'time_zone_long_name',
1350             qr/z{1,3}/ => 'time_zone_short_name',
1351             qr/ZZZZZ/ => sub {
1352             DateTime::TimeZone->offset_as_string( $_[0]->offset, q{:} );
1353             },
1354             qr/ZZZZ/ => sub {
1355             $_[0]->time_zone_short_name
1356             . DateTime::TimeZone->offset_as_string( $_[0]->offset );
1357             },
1358             qr/Z{1,3}/ =>
1359             sub { DateTime::TimeZone->offset_as_string( $_[0]->offset ) },
1360             qr/vvvv/ => 'time_zone_long_name',
1361             qr/v{1,3}/ => 'time_zone_short_name',
1362             qr/VVVV/ => 'time_zone_long_name',
1363             qr/V{1,3}/ => 'time_zone_short_name',
1364             );
1365              
1366             sub _zero_padded_number {
1367 92     92   154 my $self = shift;
1368 92         265 my $size = length shift;
1369 92         121 my $val = shift;
1370              
1371 92         667 return sprintf( "%0${size}d", $val );
1372             }
1373              
1374             sub format_cldr {
1375 129     129 1 92689 my $self = shift;
1376              
1377             # make a copy or caller's scalars get munged
1378 129         283 my @p = @_;
1379              
1380 129         181 my @r;
1381 129         232 for my $p (@p) {
1382 129         917 $p =~ s/\G
1383             (?:
1384             '((?:[^']|'')*)' # quote escaped bit of text
1385             # it needs to end with one
1386             # quote not followed by
1387             # another
1388             |
1389             (([a-zA-Z])\3*) # could be a pattern
1390             |
1391             (.) # anything else
1392             )
1393             /
1394 171 50       827 defined $1
    100          
    100          
1395             ? $1
1396             : defined $2
1397             ? $self->_cldr_pattern($2)
1398             : defined $4
1399             ? $4
1400             : undef # should never get here
1401             /sgex;
1402              
1403 129         1149 $p =~ s/\'\'/\'/g;
1404              
1405 129 50       884 return $p unless wantarray;
1406              
1407 0         0 push @r, $p;
1408             }
1409              
1410 0         0 return @r;
1411             }
1412              
1413             sub _cldr_pattern {
1414 144     144   260 my $self = shift;
1415 144         263 my $pattern = shift;
1416              
1417             ## no critic (ControlStructures::ProhibitCStyleForLoops)
1418 144         399 for ( my $i = 0; $i < @patterns; $i += 2 ) {
1419 3506 100       10006 if ( $pattern =~ /$patterns[$i]/ ) {
1420 144         416 my $sub = $patterns[ $i + 1 ];
1421              
1422 144         445 return $self->$sub();
1423             }
1424             }
1425              
1426 0         0 return $pattern;
1427             }
1428             }
1429              
1430             sub _format_nanosecs {
1431 31     31   47 my $self = shift;
1432 31 100       78 my $precision = @_ ? shift : 9;
1433              
1434 31         60 my $exponent = 9 - $precision;
1435             my $formatted_ns = floor(
1436             (
1437             $exponent < 0
1438             ? $self->{rd_nanosecs} * 10**-$exponent
1439 31 100       171 : $self->{rd_nanosecs} / 10**$exponent
1440             )
1441             );
1442              
1443 31         208 return sprintf(
1444             '%0' . $precision . 'u',
1445             $formatted_ns
1446             );
1447             }
1448              
1449             sub epoch {
1450 29     29 1 1514 my $self = shift;
1451              
1452             return $self->{utc_c}{epoch}
1453 29 100       100 if exists $self->{utc_c}{epoch};
1454              
1455             return $self->{utc_c}{epoch}
1456             = ( $self->{utc_rd_days} - 719163 ) * SECONDS_PER_DAY
1457 27         184 + $self->{utc_rd_secs};
1458             }
1459              
1460             sub hires_epoch {
1461 2     2 1 7 my $self = shift;
1462              
1463 2         4 my $epoch = $self->epoch;
1464              
1465 2 50       7 return undef unless defined $epoch;
1466              
1467 2         5 my $nano = $self->{rd_nanosecs} / MAX_NANOSECONDS;
1468              
1469 2         11 return $epoch + $nano;
1470             }
1471              
1472 0     0 1 0 sub is_finite {1}
1473 31934     31934 1 63932 sub is_infinite {0}
1474              
1475             # added for benefit of DateTime::TimeZone
1476 10     10 0 105 sub utc_year { $_[0]->{utc_year} }
1477              
1478             # returns a result that is relative to the first datetime
1479             sub subtract_datetime {
1480 55     55 1 7629 my $dt1 = shift;
1481 55         81 my $dt2 = shift;
1482              
1483 55 100       125 $dt2 = $dt2->clone->set_time_zone( $dt1->time_zone )
1484             unless $dt1->time_zone eq $dt2->time_zone;
1485              
1486             # We only want a negative duration if $dt2 > $dt1 ($self)
1487 55 100       188 my ( $bigger, $smaller, $negative ) = (
1488             $dt1 >= $dt2
1489             ? ( $dt1, $dt2, 0 )
1490             : ( $dt2, $dt1, 1 )
1491             );
1492              
1493 55   66     161 my $is_floating = $dt1->time_zone->is_floating
1494             && $dt2->time_zone->is_floating;
1495              
1496 55         195 my $minute_length = 60;
1497 55 100       118 unless ($is_floating) {
1498 43         74 my ( $utc_rd_days, $utc_rd_secs ) = $smaller->utc_rd_values;
1499              
1500 43 100 66     126 if ( $utc_rd_secs >= 86340 && !$is_floating ) {
1501              
1502             # If the smaller of the two datetimes occurs in the last
1503             # UTC minute of the UTC day, then that minute may not be
1504             # 60 seconds long. If we need to subtract a minute from
1505             # the larger datetime's minutes count in order to adjust
1506             # the seconds difference to be positive, we need to know
1507             # how long that minute was. If one of the datetimes is
1508             # floating, we just assume a minute is 60 seconds.
1509              
1510 5         20 $minute_length = $dt1->_day_length($utc_rd_days) - 86340;
1511             }
1512             }
1513              
1514             # This is a gross hack that basically figures out if the bigger of
1515             # the two datetimes is the day of a DST change. If it's a 23 hour
1516             # day (switching _to_ DST) then we subtract 60 minutes from the
1517             # local time. If it's a 25 hour day then we add 60 minutes to the
1518             # local time.
1519             #
1520             # This produces the most "intuitive" results, though there are
1521             # still reversibility problems with the resultant duration.
1522             #
1523             # However, if the two objects are on the same (local) date, and we
1524             # are not crossing a DST change, we don't want to invoke the hack
1525             # - see 38local-subtract.t
1526 55         150 my $bigger_min = $bigger->hour * 60 + $bigger->minute;
1527 55 100 100     107 if ( $bigger->time_zone->has_dst_changes
1528             && $bigger->is_dst != $smaller->is_dst ) {
1529              
1530             $bigger_min -= 60
1531              
1532             # it's a 23 hour (local) day
1533             if (
1534             $bigger->is_dst
1535 11 100 100     869 && do {
1536 5     5   428 my $prev_day = try { $bigger->clone->subtract( days => 1 ) };
  5         133  
1537 5 100 66     138 $prev_day && !$prev_day->is_dst ? 1 : 0;
1538             }
1539             );
1540              
1541             $bigger_min += 60
1542              
1543             # it's a 25 hour (local) day
1544             if (
1545             !$bigger->is_dst
1546 11 100 100     700 && do {
1547 6     6   421 my $prev_day = try { $bigger->clone->subtract( days => 1 ) };
  6         165  
1548 6 100 66     160 $prev_day && $prev_day->is_dst ? 1 : 0;
1549             }
1550             );
1551             }
1552              
1553 55         1741 my ( $months, $days, $minutes, $seconds, $nanoseconds )
1554             = $dt1->_adjust_for_positive_difference(
1555             $bigger->year * 12 + $bigger->month,
1556             $smaller->year * 12 + $smaller->month,
1557              
1558             $bigger->day, $smaller->day,
1559              
1560             $bigger_min, $smaller->hour * 60 + $smaller->minute,
1561              
1562             $bigger->second, $smaller->second,
1563              
1564             $bigger->nanosecond, $smaller->nanosecond,
1565              
1566             $minute_length,
1567              
1568             # XXX - using the smaller as the month length is
1569             # somewhat arbitrary, we could also use the bigger -
1570             # either way we have reversibility problems
1571             $dt1->_month_length( $smaller->year, $smaller->month ),
1572             );
1573              
1574 55 100       160 if ($negative) {
1575 16         41 for ( $months, $days, $minutes, $seconds, $nanoseconds ) {
1576              
1577             # Some versions of Perl can end up with -0 if we do "0 * -1"!!
1578 80 100       153 $_ *= -1 if $_;
1579             }
1580             }
1581              
1582 55         386 return $dt1->duration_class->new(
1583             months => $months,
1584             days => $days,
1585             minutes => $minutes,
1586             seconds => $seconds,
1587             nanoseconds => $nanoseconds,
1588             );
1589             }
1590              
1591             ## no critic (Subroutines::ProhibitManyArgs)
1592             sub _adjust_for_positive_difference {
1593             my (
1594 59     59   175 $self,
1595             $month1, $month2,
1596             $day1, $day2,
1597             $min1, $min2,
1598             $sec1, $sec2,
1599             $nano1, $nano2,
1600             $minute_length,
1601             $month_length,
1602             ) = @_;
1603              
1604 59 100       132 if ( $nano1 < $nano2 ) {
1605 7         10 $sec1--;
1606 7         13 $nano1 += MAX_NANOSECONDS;
1607             }
1608              
1609 59 100       147 if ( $sec1 < $sec2 ) {
1610 8         12 $min1--;
1611 8         10 $sec1 += $minute_length;
1612             }
1613              
1614             # A day always has 24 * 60 minutes, though the minutes may vary in
1615             # length.
1616 59 100       124 if ( $min1 < $min2 ) {
1617 11         29 $day1--;
1618 11         19 $min1 += 24 * 60;
1619             }
1620              
1621 59 100       139 if ( $day1 < $day2 ) {
1622 12         15 $month1--;
1623 12         15 $day1 += $month_length;
1624             }
1625              
1626             return (
1627 59         166 $month1 - $month2,
1628             $day1 - $day2,
1629             $min1 - $min2,
1630             $sec1 - $sec2,
1631             $nano1 - $nano2,
1632             );
1633             }
1634              
1635             sub subtract_datetime_absolute {
1636 8     8 1 46 my $self = shift;
1637 8         16 my $dt = shift;
1638              
1639 8         23 my $utc_rd_secs1 = $self->utc_rd_as_seconds;
1640             $utc_rd_secs1 += $self->_accumulated_leap_seconds( $self->{utc_rd_days} )
1641 8 100       26 if !$self->time_zone->is_floating;
1642              
1643 8         58 my $utc_rd_secs2 = $dt->utc_rd_as_seconds;
1644             $utc_rd_secs2 += $self->_accumulated_leap_seconds( $dt->{utc_rd_days} )
1645 8 100       22 if !$dt->time_zone->is_floating;
1646              
1647 8         45 my $seconds = $utc_rd_secs1 - $utc_rd_secs2;
1648 8         21 my $nanoseconds = $self->nanosecond - $dt->nanosecond;
1649              
1650 8 100       22 if ( $nanoseconds < 0 ) {
1651 1         2 $seconds--;
1652 1         2 $nanoseconds += MAX_NANOSECONDS;
1653             }
1654              
1655 8         53 return $self->duration_class->new(
1656             seconds => $seconds,
1657             nanoseconds => $nanoseconds,
1658             );
1659             }
1660              
1661             sub delta_md {
1662 4     4 1 4652 my $self = shift;
1663 4         9 my $dt = shift;
1664              
1665 4         18 my ( $smaller, $bigger ) = sort $self, $dt;
1666              
1667 4         15 my ( $months, $days, undef, undef, undef )
1668             = $dt->_adjust_for_positive_difference(
1669             $bigger->year * 12 + $bigger->month,
1670             $smaller->year * 12 + $smaller->month,
1671              
1672             $bigger->day, $smaller->day,
1673              
1674             0, 0,
1675              
1676             0, 0,
1677              
1678             0, 0,
1679              
1680             60,
1681              
1682             $smaller->_month_length( $smaller->year, $smaller->month ),
1683             );
1684              
1685 4         27 return $self->duration_class->new(
1686             months => $months,
1687             days => $days
1688             );
1689             }
1690              
1691             sub delta_days {
1692 6     6 1 3887 my $self = shift;
1693 6         12 my $dt = shift;
1694              
1695 6         24 my $days
1696             = abs( ( $self->local_rd_values )[0] - ( $dt->local_rd_values )[0] );
1697              
1698 6         33 $self->duration_class->new( days => $days );
1699             }
1700              
1701             sub delta_ms {
1702 3     3 1 10 my $self = shift;
1703 3         5 my $dt = shift;
1704              
1705 3         12 my ( $smaller, $greater ) = sort $self, $dt;
1706              
1707 3         9 my $days = int( $greater->jd - $smaller->jd );
1708              
1709 3         9 my $dur = $greater->subtract_datetime($smaller);
1710              
1711 3         4 my %p;
1712 3         10 $p{hours} = $dur->hours + ( $days * 24 );
1713 3         9 $p{minutes} = $dur->minutes;
1714 3         8 $p{seconds} = $dur->seconds;
1715              
1716 3         15 return $self->duration_class->new(%p);
1717             }
1718              
1719             sub _add_overload {
1720 9133     9133   27222 my ( $dt, $dur, $reversed ) = @_;
1721              
1722 9133 50       18050 if ($reversed) {
1723 0         0 ( $dur, $dt ) = ( $dt, $dur );
1724             }
1725              
1726 9133 100       22401 unless ( DateTime::Helpers::isa( $dur, 'DateTime::Duration' ) ) {
1727 2         6 my $class = ref $dt;
1728 2         7 my $dt_string = overload::StrVal($dt);
1729              
1730 2         279 Carp::croak( "Cannot add $dur to a $class object ($dt_string).\n"
1731             . ' Only a DateTime::Duration object can '
1732             . " be added to a $class object." );
1733             }
1734              
1735 9131         22978 return $dt->clone->add_duration($dur);
1736             }
1737              
1738             sub _subtract_overload {
1739 22828     22828   116901 my ( $date1, $date2, $reversed ) = @_;
1740              
1741 22828 50       43927 if ($reversed) {
1742 0         0 ( $date2, $date1 ) = ( $date1, $date2 );
1743             }
1744              
1745 22828 100       60377 if ( DateTime::Helpers::isa( $date2, 'DateTime::Duration' ) ) {
    100          
1746 22806         48045 my $new = $date1->clone;
1747 22806         64763 $new->add_duration( $date2->inverse );
1748 22806         443995 return $new;
1749             }
1750             elsif ( DateTime::Helpers::isa( $date2, 'DateTime' ) ) {
1751 20         73 return $date1->subtract_datetime($date2);
1752             }
1753             else {
1754 2         4 my $class = ref $date1;
1755 2         8 my $dt_string = overload::StrVal($date1);
1756              
1757 2         206 Carp::croak(
1758             "Cannot subtract $date2 from a $class object ($dt_string).\n"
1759             . ' Only a DateTime::Duration or DateTime object can '
1760             . " be subtracted from a $class object." );
1761             }
1762             }
1763              
1764             sub add {
1765 648     648 1 3145 my $self = shift;
1766              
1767 648         1556 return $self->add_duration( $self->_duration_object_from_args(@_) );
1768             }
1769              
1770             sub subtract {
1771 54     54 1 232 my $self = shift;
1772              
1773 54         90 my %eom;
1774 54 100       189 if ( @_ % 2 == 0 ) {
1775 53         163 my %p = @_;
1776              
1777             $eom{end_of_month} = delete $p{end_of_month}
1778 53 100       188 if exists $p{end_of_month};
1779             }
1780              
1781 54         137 my $dur = $self->_duration_object_from_args(@_)->inverse(%eom);
1782              
1783 54         267 return $self->add_duration($dur);
1784             }
1785              
1786             # Syntactic sugar for add and subtract: use a duration object if it's
1787             # supplied, otherwise build a new one from the arguments.
1788              
1789             sub _duration_object_from_args {
1790 702     702   1034 my $self = shift;
1791              
1792 702 50 66     1811 return $_[0]
      66        
1793             if @_ == 1 && blessed( $_[0] ) && $_[0]->isa( $self->duration_class );
1794              
1795 700         3140 return $self->duration_class->new(@_);
1796             }
1797              
1798 17     17 1 92 sub subtract_duration { return $_[0]->add_duration( $_[1]->inverse ) }
1799              
1800             {
1801             my $validator = validation_for(
1802             name => '_check_add_duration_params',
1803             name_is_optional => 1,
1804             params => [
1805             { type => t('Duration') },
1806             ],
1807             );
1808              
1809             ## no critic (Subroutines::ProhibitExcessComplexity)
1810             sub add_duration {
1811 32684     32684 1 54078 my $self = shift;
1812 32684         627114 my ($dur) = $validator->(@_);
1813              
1814             # simple optimization
1815 32684 100       398552 return $self if $dur->is_zero;
1816              
1817 31940         76777 my %deltas = $dur->deltas;
1818              
1819             # This bit isn't quite right since DateTime::Infinite::Future -
1820             # infinite duration should NaN
1821 31940         92364 for my $val ( values %deltas ) {
1822 159692         179871 my $inf;
1823 159692 100       315796 if ( $val == INFINITY ) {
    100          
1824 1         7 $inf = DateTime::Infinite::Future->new;
1825             }
1826             elsif ( $val == NEG_INFINITY ) {
1827 1         5 $inf = DateTime::Infinite::Past->new;
1828             }
1829              
1830 159692 100       273032 if ($inf) {
1831 2         31 %$self = %$inf;
1832 2         8 bless $self, ref $inf;
1833              
1834 2         10 return $self;
1835             }
1836             }
1837              
1838 31938 100       65142 return $self if $self->is_infinite;
1839              
1840 31934         47086 my %orig = %{$self};
  31934         214137  
1841             try {
1842 31934     31934   1291523 $self->_add_duration($dur);
1843             }
1844             catch {
1845 2     2   259 %{$self} = %orig;
  2         13  
1846 2         16 die $_;
1847 31934         205838 };
1848             }
1849             }
1850              
1851             sub _add_duration {
1852 31934     31934   46317 my $self = shift;
1853 31934         39683 my $dur = shift;
1854              
1855 31934         67854 my %deltas = $dur->deltas;
1856              
1857 31934 100       81634 if ( $deltas{days} ) {
1858 23769         42975 $self->{local_rd_days} += $deltas{days};
1859              
1860 23769         59980 $self->{utc_year} += int( $deltas{days} / 365 ) + 1;
1861             }
1862              
1863 31934 100       63853 if ( $deltas{months} ) {
1864              
1865             # For preserve mode, if it is the last day of the month, make
1866             # it the 0th day of the following month (which then will
1867             # normalize back to the last day of the new month).
1868             my ( $y, $m, $d ) = (
1869             $dur->is_preserve_mode
1870             ? $self->_rd2ymd( $self->{local_rd_days} + 1 )
1871             : $self->_rd2ymd( $self->{local_rd_days} )
1872 540 100       1222 );
1873              
1874 540 100       1286 $d -= 1 if $dur->is_preserve_mode;
1875              
1876 540 100 100     1103 if ( !$dur->is_wrap_mode && $d > 28 ) {
1877              
1878             # find the rd for the last day of our target month
1879             $self->{local_rd_days}
1880 2         13 = $self->_ymd2rd( $y, $m + $deltas{months} + 1, 0 );
1881              
1882             # what day of the month is it? (discard year and month)
1883             my $last_day
1884 2         10 = ( $self->_rd2ymd( $self->{local_rd_days} ) )[2];
1885              
1886             # if our original day was less than the last day,
1887             # use that instead
1888 2 100       8 $self->{local_rd_days} -= $last_day - $d if $last_day > $d;
1889             }
1890             else {
1891             $self->{local_rd_days}
1892 538         1714 = $self->_ymd2rd( $y, $m + $deltas{months}, $d );
1893             }
1894              
1895 540         1655 $self->{utc_year} += int( $deltas{months} / 12 ) + 1;
1896             }
1897              
1898 31934 100 100     82420 if ( $deltas{days} || $deltas{months} ) {
1899 24306         58354 $self->_calc_utc_rd;
1900              
1901 24304         49304 $self->_handle_offset_modifier( $self->second );
1902             }
1903              
1904 31932 100       119128 if ( $deltas{minutes} ) {
1905 74         179 $self->{utc_rd_secs} += $deltas{minutes} * 60;
1906              
1907             # This intentionally ignores leap seconds
1908             $self->_normalize_tai_seconds(
1909             $self->{utc_rd_days},
1910             $self->{utc_rd_secs}
1911 74         259 );
1912             }
1913              
1914 31932 100 100     93201 if ( $deltas{seconds} || $deltas{nanoseconds} ) {
1915 7577         12953 $self->{utc_rd_secs} += $deltas{seconds};
1916              
1917 7577 100       14140 if ( $deltas{nanoseconds} ) {
1918 3         12 $self->{rd_nanosecs} += $deltas{nanoseconds};
1919             $self->_normalize_nanoseconds(
1920             $self->{utc_rd_secs},
1921             $self->{rd_nanosecs}
1922 3         8 );
1923             }
1924              
1925 7577         19996 $self->_normalize_seconds;
1926              
1927             # This might be some big number much bigger than 60, but
1928             # that's ok (there are tests in 19leap_second.t to confirm
1929             # that)
1930 7577         15570 $self->_handle_offset_modifier( $self->second + $deltas{seconds} );
1931             }
1932              
1933             my $new = ( ref $self )->from_object(
1934             object => $self,
1935             locale => $self->{locale},
1936 31932 50       126236 ( $self->{formatter} ? ( formatter => $self->{formatter} ) : () ),
1937             );
1938              
1939 31932         267385 %$self = %$new;
1940              
1941 31932         173279 return $self;
1942             }
1943              
1944             sub _compare_overload {
1945              
1946             # note: $_[1]->compare( $_[0] ) is an error when $_[1] is not a
1947             # DateTime (such as the INFINITY value)
1948              
1949 8932 100   8932   87293 return undef unless defined $_[1];
1950              
1951 8930 100       17142 return $_[2] ? -$_[0]->compare( $_[1] ) : $_[0]->compare( $_[1] );
1952             }
1953              
1954             sub _string_compare_overload {
1955 22     22   2273 my ( $dt1, $dt2, $flip ) = @_;
1956              
1957             # One is a DateTime object, one isn't. Just stringify and compare.
1958 22 100       66 if ( !DateTime::Helpers::can( $dt2, 'utc_rd_values' ) ) {
1959 12 100       25 my $sign = $flip ? -1 : 1;
1960 12         27 return $sign * ( "$dt1" cmp "$dt2" );
1961             }
1962             else {
1963 10         42 my $meth = $dt1->can('_compare_overload');
1964 10         34 goto $meth;
1965             }
1966             }
1967              
1968             sub compare {
1969 9007     9007 1 16349 shift->_compare( @_, 0 );
1970             }
1971              
1972             sub compare_ignore_floating {
1973 2     2 1 7 shift->_compare( @_, 1 );
1974             }
1975              
1976             sub _compare {
1977 9009 100   9009   18201 my ( undef, $dt1, $dt2, $consistent ) = ref $_[0] ? ( undef, @_ ) : @_;
1978              
1979 9009 50       15298 return undef unless defined $dt2;
1980              
1981 9009 100 100     16218 if ( !ref $dt2 && ( $dt2 == INFINITY || $dt2 == NEG_INFINITY ) ) {
      100        
1982 6         91 return $dt1->{utc_rd_days} <=> $dt2;
1983             }
1984              
1985 9003 100 66     16489 unless ( DateTime::Helpers::can( $dt1, 'utc_rd_values' )
1986             && DateTime::Helpers::can( $dt2, 'utc_rd_values' ) ) {
1987 2         6 my $dt1_string = overload::StrVal($dt1);
1988 2         11 my $dt2_string = overload::StrVal($dt2);
1989              
1990 2         200 Carp::croak( 'A DateTime object can only be compared to'
1991             . " another DateTime object ($dt1_string, $dt2_string)." );
1992             }
1993              
1994 9001 100 66     21118 if ( !$consistent
      100        
1995             && DateTime::Helpers::can( $dt1, 'time_zone' )
1996             && DateTime::Helpers::can( $dt2, 'time_zone' ) ) {
1997 8997         14521 my $is_floating1 = $dt1->time_zone->is_floating;
1998 8997         25576 my $is_floating2 = $dt2->time_zone->is_floating;
1999              
2000 8997 100 100     46235 if ( $is_floating1 && !$is_floating2 ) {
    100 100        
2001 2         15 $dt1 = $dt1->clone->set_time_zone( $dt2->time_zone );
2002             }
2003             elsif ( $is_floating2 && !$is_floating1 ) {
2004 3         19 $dt2 = $dt2->clone->set_time_zone( $dt1->time_zone );
2005             }
2006             }
2007              
2008 9001         14761 my @dt1_components = $dt1->utc_rd_values;
2009 9001         13408 my @dt2_components = $dt2->utc_rd_values;
2010              
2011 9001         14867 for my $i ( 0 .. 2 ) {
2012 9172 100       31068 return $dt1_components[$i] <=> $dt2_components[$i]
2013             if $dt1_components[$i] != $dt2_components[$i];
2014             }
2015              
2016 68         541 return 0;
2017             }
2018              
2019             sub is_between {
2020 5     5 1 120 my $self = shift;
2021 5         7 my $lower = shift;
2022 5         7 my $upper = shift;
2023              
2024 5   100     11 return $self->compare($lower) > 0 && $self->compare($upper) < 0;
2025             }
2026              
2027             sub _string_equals_overload {
2028 16 50   16   2231 my ( $class, $dt1, $dt2 ) = ref $_[0] ? ( undef, @_ ) : @_;
2029              
2030 16 100       54 if ( !DateTime::Helpers::can( $dt2, 'utc_rd_values' ) ) {
2031 10         21 return "$dt1" eq "$dt2";
2032             }
2033              
2034 6   33     38 $class ||= ref $dt1;
2035 6         23 return !$class->compare( $dt1, $dt2 );
2036             }
2037              
2038             sub _string_not_equals_overload {
2039 6     6   646 return !_string_equals_overload(@_);
2040             }
2041              
2042             sub _normalize_nanoseconds {
2043 49     49   501647 use integer;
  49         156  
  49         305  
2044              
2045             # seconds, nanoseconds
2046 57558 100   57558   177297 if ( $_[2] < 0 ) {
    100          
2047 1         5 my $overflow = 1 + $_[2] / MAX_NANOSECONDS;
2048 1         3 $_[2] += $overflow * MAX_NANOSECONDS;
2049 1         2 $_[1] -= $overflow;
2050             }
2051             elsif ( $_[2] >= MAX_NANOSECONDS ) {
2052 1         4 my $overflow = $_[2] / MAX_NANOSECONDS;
2053 1         6 $_[2] -= $overflow * MAX_NANOSECONDS;
2054 1         3 $_[1] += $overflow;
2055             }
2056             }
2057              
2058             {
2059             my $validator = validation_for(
2060             name => '_check_set_params',
2061             name_is_optional => 1,
2062             params => {
2063             year => {
2064             type => t('Year'),
2065             optional => 1,
2066             },
2067             month => {
2068             type => t('Month'),
2069             optional => 1,
2070             },
2071             day => {
2072             type => t('DayOfMonth'),
2073             optional => 1,
2074             },
2075             hour => {
2076             type => t('Hour'),
2077             optional => 1,
2078             },
2079             minute => {
2080             type => t('Minute'),
2081             optional => 1,
2082             },
2083             second => {
2084             type => t('Second'),
2085             optional => 1,
2086             },
2087             nanosecond => {
2088             type => t('Nanosecond'),
2089             optional => 1,
2090             },
2091             locale => {
2092             type => t('Locale'),
2093             optional => 1,
2094             },
2095             },
2096             );
2097              
2098             ## no critic (NamingConventions::ProhibitAmbiguousNames)
2099             sub set {
2100 41     41 1 743 my $self = shift;
2101 41         1024 my %p = $validator->(@_);
2102              
2103 31 50       1596 if ( $p{locale} ) {
2104 0         0 carp 'You passed a locale to the set() method.'
2105             . ' You should use set_locale() instead, as using set() may alter the local time near a DST boundary.';
2106             }
2107              
2108 31         130 my $new_dt = $self->_new_from_self(%p);
2109              
2110 31         283 %$self = %$new_dt;
2111              
2112 31         177 return $self;
2113             }
2114             }
2115              
2116 1     1 1 12 sub set_year { $_[0]->set( year => $_[1] ) }
2117 1     1 1 4 sub set_month { $_[0]->set( month => $_[1] ) }
2118 1     1 1 6 sub set_day { $_[0]->set( day => $_[1] ) }
2119 1     1 1 4 sub set_hour { $_[0]->set( hour => $_[1] ) }
2120 1     1 1 5 sub set_minute { $_[0]->set( minute => $_[1] ) }
2121 1     1 1 4 sub set_second { $_[0]->set( second => $_[1] ) }
2122 1     1 1 4 sub set_nanosecond { $_[0]->set( nanosecond => $_[1] ) }
2123              
2124             # These two are special cased because ... if the local time is the hour of a
2125             # DST change where the same local time occurs twice then passing it through
2126             # _new() can actually change the underlying UTC time, which is bad.
2127              
2128             {
2129             my $validator = validation_for(
2130             name => '_check_set_locale_params',
2131             name_is_optional => 1,
2132             params => [
2133             { type => t( 'Maybe', of => t('Locale') ) },
2134             ],
2135             );
2136              
2137             sub set_locale {
2138 2     2 1 5 my $self = shift;
2139 2         57 my ($locale) = $validator->(@_);
2140              
2141 2         54 $self->_set_locale($locale);
2142              
2143 2         7 return $self;
2144             }
2145             }
2146              
2147             {
2148             my $validator = validation_for(
2149             name => '_check_set_formatter_params',
2150             name_is_optional => 1,
2151             params => [
2152             { type => t( 'Maybe', of => t('Formatter') ) },
2153             ],
2154             );
2155              
2156             sub set_formatter {
2157 2     2 1 101 my $self = shift;
2158 2         53 my ($formatter) = $validator->(@_);
2159              
2160 1         13 $self->{formatter} = $formatter;
2161              
2162 1         3 return $self;
2163             }
2164             }
2165              
2166             {
2167             my %TruncateDefault = (
2168             month => 1,
2169             day => 1,
2170             hour => 0,
2171             minute => 0,
2172             second => 0,
2173             nanosecond => 0,
2174             );
2175              
2176             my $validator = validation_for(
2177             name => '_check_truncate_params',
2178             name_is_optional => 1,
2179             params => {
2180             to => { type => t('TruncationLevel') },
2181             },
2182             );
2183              
2184             my $re = join '|', 'year', 'week', 'local_week', 'quarter',
2185             grep { $_ ne 'nanosecond' } keys %TruncateDefault;
2186             my $spec = { to => { regex => qr/^(?:$re)$/ } };
2187              
2188             ## no critic (Subroutines::ProhibitBuiltinHomonyms)
2189             sub truncate {
2190 174     174 1 117311 my $self = shift;
2191 174         4191 my %p = $validator->(@_);
2192              
2193 170         3814 my %new;
2194 170 100 100     916 if ( $p{to} eq 'week' || $p{to} eq 'local_week' ) {
    100          
2195             my $first_day_of_week
2196             = ( $p{to} eq 'local_week' )
2197             ? $self->{locale}->first_day_of_week
2198 25 100       85 : 1;
2199              
2200 25         103 my $day_diff = ( $self->day_of_week - $first_day_of_week ) % 7;
2201              
2202 25 100       78 if ($day_diff) {
2203 22         68 $self->add( days => -1 * $day_diff );
2204             }
2205              
2206             # This can fail if the truncate ends up giving us an invalid local
2207             # date time. If that happens we need to reverse the addition we
2208             # just did. See https://rt.cpan.org/Ticket/Display.html?id=93347.
2209             try {
2210 25     25   925 $self->truncate( to => 'day' );
2211             }
2212             catch {
2213 1     1   117 $self->add( days => $day_diff );
2214 1         20 die $_;
2215 25         467 };
2216             }
2217             elsif ( $p{to} eq 'quarter' ) {
2218 108         323 %new = (
2219             year => $self->year,
2220             month => int( ( $self->month - 1 ) / 3 ) * 3 + 1,
2221             day => 1,
2222             hour => 0,
2223             minute => 0,
2224             second => 0,
2225             nanosecond => 0,
2226             );
2227             }
2228             else {
2229 37         75 my $truncate;
2230 37         86 for my $f (qw( year month day hour minute second nanosecond )) {
2231 259 100       627 $new{$f} = $truncate ? $TruncateDefault{$f} : $self->$f();
2232              
2233 259 100       515 $truncate = 1 if $p{to} eq $f;
2234             }
2235             }
2236              
2237 169         861 my $new_dt = $self->_new_from_self( %new, _skip_validation => 1 );
2238              
2239 168         1418 %$self = %$new_dt;
2240              
2241 168         883 return $self;
2242             }
2243             }
2244              
2245             sub set_time_zone {
2246 32003     32003 1 57988 my ( $self, $tz ) = @_;
2247              
2248 32003 100       65760 if ( ref $tz ) {
2249              
2250             # This is a bit of a hack but it works because time zone objects
2251             # are singletons, and if it doesn't work all we lose is a little
2252             # bit of speed.
2253 31951 100       108183 return $self if $self->{tz} eq $tz;
2254             }
2255             else {
2256 52 100       257 return $self if $self->{tz}->name eq $tz;
2257             }
2258              
2259 31415         81899 my $was_floating = $self->{tz}->is_floating;
2260              
2261 31415         95261 my $old_tz = $self->{tz};
2262 31415 100       64123 $self->{tz} = ref $tz ? $tz : DateTime::TimeZone->new( name => $tz );
2263              
2264 31415         119817 $self->_handle_offset_modifier( $self->second, 1 );
2265              
2266 31415         114610 my $e;
2267             try {
2268             # if it either was or now is floating (but not both)
2269 31415 100 75 31415   1299323 if ( $self->{tz}->is_floating xor $was_floating ) {
    50          
2270 31259         188657 $self->_calc_utc_rd;
2271             }
2272             elsif ( !$was_floating ) {
2273 156         1292 $self->_calc_local_rd;
2274             }
2275             }
2276             catch {
2277 1     1   133 $e = $_;
2278 31415         197405 };
2279              
2280             # If we can't recalc the RD values then we shouldn't keep the new TZ. RT
2281             # #83940
2282 31415 100       454488 if ($e) {
2283 1         3 $self->{tz} = $old_tz;
2284 1         5 die $e;
2285             }
2286              
2287 31414         59855 return $self;
2288             }
2289              
2290             sub STORABLE_freeze {
2291 4     4 0 194 my $self = shift;
2292              
2293 4         7 my $serialized = q{};
2294 4         9 for my $key (
2295             qw( utc_rd_days
2296             utc_rd_secs
2297             rd_nanosecs )
2298             ) {
2299 12         37 $serialized .= "$key:$self->{$key}|";
2300             }
2301              
2302             # not used yet, but may be handy in the future.
2303 4   50     14 $serialized .= 'version:' . ( $DateTime::VERSION || 'git' );
2304              
2305             # Formatter needs to be returned as a reference since it may be
2306             # undef or a class name, and Storable will complain if extra
2307             # return values aren't refs
2308 4         36 return $serialized, $self->{locale}, $self->{tz}, \$self->{formatter};
2309             }
2310              
2311             sub STORABLE_thaw {
2312 4     4 0 1304 my $self = shift;
2313 4         7 shift;
2314 4         5 my $serialized = shift;
2315              
2316 4         18 my %serialized = map { split /:/ } split /\|/, $serialized;
  16         40  
2317              
2318 4         98 my ( $locale, $tz, $formatter );
2319              
2320             # more recent code version
2321 4 50       13 if (@_) {
2322 4         11 ( $locale, $tz, $formatter ) = @_;
2323             }
2324             else {
2325 0         0 $tz = DateTime::TimeZone->new( name => delete $serialized{tz} );
2326              
2327 0         0 $locale = DateTime::Locale->load( delete $serialized{locale} );
2328             }
2329              
2330 4         21 delete $serialized{version};
2331              
2332             my $object = bless {
2333             utc_vals => [
2334             $serialized{utc_rd_days},
2335             $serialized{utc_rd_secs},
2336             $serialized{rd_nanosecs},
2337 4         28 ],
2338             tz => $tz,
2339             },
2340             'DateTime::_Thawed';
2341              
2342 4 100       38 my %formatter = defined $$formatter ? ( formatter => $$formatter ) : ();
2343 4         19 my $new = ( ref $self )->from_object(
2344             object => $object,
2345             locale => $locale,
2346             %formatter,
2347             );
2348              
2349 4         27 %$self = %$new;
2350              
2351 4         59 return $self;
2352             }
2353              
2354             ## no critic (Modules::ProhibitMultiplePackages)
2355             package # hide from PAUSE
2356             DateTime::_Thawed;
2357              
2358 4     4   6 sub utc_rd_values { @{ $_[0]->{utc_vals} } }
  4         17  
2359              
2360 8     8   25 sub time_zone { $_[0]->{tz} }
2361              
2362             1;
2363              
2364             # ABSTRACT: A date and time object for Perl
2365              
2366             __END__
2367              
2368             =pod
2369              
2370             =encoding UTF-8
2371              
2372             =head1 NAME
2373              
2374             DateTime - A date and time object for Perl
2375              
2376             =head1 VERSION
2377              
2378             version 1.60
2379              
2380             =head1 SYNOPSIS
2381              
2382             use DateTime;
2383              
2384             $dt = DateTime->new(
2385             year => 1964,
2386             month => 10,
2387             day => 16,
2388             hour => 16,
2389             minute => 12,
2390             second => 47,
2391             nanosecond => 500000000,
2392             time_zone => 'Asia/Taipei',
2393             );
2394              
2395             $dt = DateTime->from_epoch( epoch => $epoch );
2396             $dt = DateTime->now; # same as ( epoch => time )
2397              
2398             $year = $dt->year;
2399             $month = $dt->month; # 1-12
2400              
2401             $day = $dt->day; # 1-31
2402              
2403             $dow = $dt->day_of_week; # 1-7 (Monday is 1)
2404              
2405             $hour = $dt->hour; # 0-23
2406             $minute = $dt->minute; # 0-59
2407              
2408             $second = $dt->second; # 0-61 (leap seconds!)
2409              
2410             $doy = $dt->day_of_year; # 1-366 (leap years)
2411              
2412             $doq = $dt->day_of_quarter; # 1..
2413              
2414             $qtr = $dt->quarter; # 1-4
2415              
2416             # all of the start-at-1 methods above have corresponding start-at-0
2417             # methods, such as $dt->day_of_month_0, $dt->month_0 and so on
2418              
2419             $ymd = $dt->ymd; # 2002-12-06
2420             $ymd = $dt->ymd('/'); # 2002/12/06
2421              
2422             $mdy = $dt->mdy; # 12-06-2002
2423             $mdy = $dt->mdy('/'); # 12/06/2002
2424              
2425             $dmy = $dt->dmy; # 06-12-2002
2426             $dmy = $dt->dmy('/'); # 06/12/2002
2427              
2428             $hms = $dt->hms; # 14:02:29
2429             $hms = $dt->hms('!'); # 14!02!29
2430              
2431             $is_leap = $dt->is_leap_year;
2432              
2433             # these are localizable, see Locales section
2434             $month_name = $dt->month_name; # January, February, ...
2435             $month_abbr = $dt->month_abbr; # Jan, Feb, ...
2436             $day_name = $dt->day_name; # Monday, Tuesday, ...
2437             $day_abbr = $dt->day_abbr; # Mon, Tue, ...
2438              
2439             # May not work for all possible datetime, see the docs on this
2440             # method for more details.
2441             $epoch_time = $dt->epoch;
2442              
2443             $dt2 = $dt + $duration_object;
2444              
2445             $dt3 = $dt - $duration_object;
2446              
2447             $duration_object = $dt - $dt2;
2448              
2449             $dt->set( year => 1882 );
2450              
2451             $dt->set_time_zone('America/Chicago');
2452              
2453             $dt->set_formatter($formatter);
2454              
2455             =head1 DESCRIPTION
2456              
2457             DateTime is a class for the representation of date/time combinations, and is
2458             part of the Perl DateTime project.
2459              
2460             It represents the Gregorian calendar, extended backwards in time before its
2461             creation (in 1582). This is sometimes known as the "proleptic Gregorian
2462             calendar". In this calendar, the first day of the calendar (the epoch), is the
2463             first day of year 1, which corresponds to the date which was (incorrectly)
2464             believed to be the birth of Jesus Christ.
2465              
2466             The calendar represented does have a year 0, and in that way differs from how
2467             dates are often written using "BCE/CE" or "BC/AD".
2468              
2469             For infinite datetimes, please see the L<DateTime::Infinite|DateTime::Infinite>
2470             module.
2471              
2472             =head1 USAGE
2473              
2474             =head2 0-based Versus 1-based Numbers
2475              
2476             The C<DateTime> module follows a simple logic for determining whether or not a
2477             given number is 0-based or 1-based.
2478              
2479             Month, day of month, day of week, and day of year are 1-based. Any method that
2480             is 1-based also has an equivalent 0-based method ending in C<_0>. So for
2481             example, this class provides both C<day_of_week> and C<day_of_week_0> methods.
2482              
2483             The C<day_of_week_0> method still treats Monday as the first day of the week.
2484              
2485             All I<time>-related numbers such as hour, minute, and second are 0-based.
2486              
2487             Years are neither, as they can be both positive or negative, unlike any other
2488             datetime component. There I<is> a year 0.
2489              
2490             There is no C<quarter_0> method.
2491              
2492             =head2 Error Handling
2493              
2494             Some errors may cause this module to die with an error string. This can only
2495             happen when calling constructor methods, methods that change the object, such
2496             as C<set>, or methods that take parameters. Methods that retrieve information
2497             about the object, such as C<year> or C<epoch>, will never die.
2498              
2499             =head2 Locales
2500              
2501             All the object methods which return names or abbreviations return data based on
2502             a locale. This is done by setting the locale when constructing a DateTime
2503             object. If this is not set, then C<"en-US"> is used.
2504              
2505             =head2 Floating DateTimes
2506              
2507             The default time zone for new DateTime objects, except where stated otherwise,
2508             is the "floating" time zone. This concept comes from the iCal standard. A
2509             floating datetime is one which is not anchored to any particular time zone. In
2510             addition, floating datetimes do not include leap seconds, since we cannot apply
2511             them without knowing the datetime's time zone.
2512              
2513             The results of date math and comparison between a floating datetime and one
2514             with a real time zone are not really valid, because one includes leap seconds
2515             and the other does not. Similarly, the results of datetime math between two
2516             floating datetimes and two datetimes with time zones are not really comparable.
2517              
2518             If you are planning to use any objects with a real time zone, it is strongly
2519             recommended that you B<do not> mix these with floating datetimes.
2520              
2521             =head2 Math
2522              
2523             If you are going to be doing date math, please read the section L<How DateTime
2524             Math Works>.
2525              
2526             =head2 Determining the Local Time Zone Can Be Slow
2527              
2528             If C<$ENV{TZ}> is not set, it may involve reading a number of files in F</etc>
2529             or elsewhere. If you know that the local time zone won't change while your code
2530             is running, and you need to make many objects for the local time zone, it is
2531             strongly recommended that you retrieve the local time zone once and cache it:
2532              
2533             my $local_time_zone = DateTime::TimeZone->new( name => 'local' );
2534              
2535             # then everywhere else
2536              
2537             my $dt = DateTime->new( ..., time_zone => $local_time_zone );
2538              
2539             DateTime itself does not do this internally because local time zones can
2540             change, and there's no good way to determine if it's changed without doing all
2541             the work to look it up.
2542              
2543             =head2 Far Future DST
2544              
2545             Do not try to use named time zones (like "America/Chicago") with dates very far
2546             in the future (thousands of years). The current implementation of
2547             C<DateTime::TimeZone> will use a huge amount of memory calculating all the DST
2548             changes from now until the future date. Use UTC or the floating time zone and
2549             you will be safe.
2550              
2551             =head2 Globally Setting a Default Time Zone
2552              
2553             B<Warning: This is very dangerous. Do this at your own risk!>
2554              
2555             By default, C<DateTime> uses either the floating time zone or UTC for newly
2556             created objects, depending on the constructor.
2557              
2558             You can force C<DateTime> to use a different time zone by setting the
2559             C<PERL_DATETIME_DEFAULT_TZ> environment variable.
2560              
2561             As noted above, this is very dangerous, as it affects all code that creates a
2562             C<DateTime> object, including modules from CPAN. If those modules expect the
2563             normal default, then setting this can cause confusing breakage or subtly broken
2564             data. Before setting this variable, you are strongly encouraged to audit your
2565             CPAN dependencies to see how they use C<DateTime>. Try running the test suite
2566             for each dependency with this environment variable set before using this in
2567             production.
2568              
2569             =head2 Upper and Lower Bounds
2570              
2571             Internally, dates are represented the number of days before or after
2572             0001-01-01. This is stored as an integer, meaning that the upper and lower
2573             bounds are based on your Perl's integer size (C<$Config{ivsize}>).
2574              
2575             The limit on 32-bit systems is around 2^29 days, which gets you to year
2576             (+/-)1,469,903. On a 64-bit system you get 2^62 days, to year
2577             (+/-)12,626,367,463,883,278 (12.626 quadrillion).
2578              
2579             =head1 METHODS
2580              
2581             DateTime provides many methods. The documentation breaks them down into groups
2582             based on what they do (constructor, accessors, modifiers, etc.).
2583              
2584             =head2 Constructors
2585              
2586             All constructors can die when invalid parameters are given.
2587              
2588             =head3 Warnings
2589              
2590             Currently, constructors will warn if you try to create a far future DateTime
2591             (year >= 5000) with any time zone besides floating or UTC. This can be very
2592             slow if the time zone has future DST transitions that need to be calculated. If
2593             the date is sufficiently far in the future this can be I<really> slow
2594             (minutes).
2595              
2596             All warnings from DateTime use the C<DateTime> category and can be suppressed
2597             with:
2598              
2599             no warnings 'DateTime';
2600              
2601             This warning may be removed in the future if L<DateTime::TimeZone> is made much
2602             faster.
2603              
2604             =head3 DateTime->new( ... )
2605              
2606             my $dt = DateTime->new(
2607             year => 1966,
2608             month => 10,
2609             day => 25,
2610             hour => 7,
2611             minute => 15,
2612             second => 47,
2613             nanosecond => 500000000,
2614             time_zone => 'America/Chicago',
2615             );
2616              
2617             This class method accepts the following parameters:
2618              
2619             =over 4
2620              
2621             =item * year
2622              
2623             An integer year for the DateTime. This can be any integer number within the
2624             valid range for your system (See L</Upper and Lower Bounds>). This is required.
2625              
2626             =item * month
2627              
2628             An integer from 1-12. Defaults to 1.
2629              
2630             =item * day
2631              
2632             An integer from 1-31. The value will be validated based on the month, to
2633             prevent creating invalid dates like February 30. Defaults to 1.
2634              
2635             =item * hour
2636              
2637             An integer from 0-23. Hour 0 is midnight at the beginning of the given date.
2638             Defaults to 0.
2639              
2640             =item * minute
2641              
2642             An integer from 0-59. Defaults to 0.
2643              
2644             =item * second
2645              
2646             An integer from 0-61. Values of 60 or 61 are only allowed when the specified
2647             date and time have a leap second. Defaults to 0.
2648              
2649             =item * nanosecond
2650              
2651             An integer that is greater than or equal to 0. If this number is greater than 1
2652             billion, it will be normalized into the second value for the DateTime object.
2653             Defaults to 0
2654              
2655             =item * locale
2656              
2657             A string containing a locale code, like C<"en-US"> or C<"zh-Hant-TW">, or an
2658             object returned by C<< DateTime::Locale->load >>. See the L<DateTime::Locale>
2659             documentation for details. Defaults to the value of C<< DateTime->DefaultLocale
2660             >>, or C<"en-US"> if the class default has not been set.
2661              
2662             =item * time_zone
2663              
2664             A string containing a time zone name like "America/Chicago" or a
2665             L<DateTime::TimeZone> object. Defaults to the value of
2666             C<$ENV{PERL_DATETIME_DEFAULT_TZ}> or "floating" if that env var is not set. See
2667             L</Globally Setting a Default Time Zone> for more details on that env var (and
2668             why you should not use it).
2669              
2670             A string will simply be passed to the C<< DateTime::TimeZone->new >> method as
2671             its C<name> parameter. This string may be an Olson DB time zone name
2672             ("America/Chicago"), an offset string ("+0630"), or the words "floating" or
2673             "local". See the C<DateTime::TimeZone> documentation for more details.
2674              
2675             =item * formatter
2676              
2677             An object or class name with a C<format_datetime> method. This will be used to
2678             stringify the DateTime object. This is optional. If it is not specified, then
2679             stringification calls C<< $self->iso8601 >>.
2680              
2681             =back
2682              
2683             Invalid parameter types (like an array reference) will cause the constructor to
2684             die.
2685              
2686             =head4 Parsing Dates
2687              
2688             B<This module does not parse dates!> That means there is no constructor to
2689             which you can pass things like "March 3, 1970 12:34".
2690              
2691             Instead, take a look at the various
2692             L<DateTime::Format::*|https://metacpan.org/search?q=datetime%3A%3Aformat>
2693             modules on CPAN. These parse all sorts of different date formats, and you're
2694             bound to find something that can handle your particular needs.
2695              
2696             =head4 Ambiguous Local Times
2697              
2698             Because of Daylight Saving Time, it is possible to specify a local time that is
2699             ambiguous. For example, in the US in 2003, the transition from to saving to
2700             standard time occurred on October 26, at 02:00:00 local time. The local clock
2701             changed from 01:59:59 (saving time) to 01:00:00 (standard time). This means
2702             that the hour from 01:00:00 through 01:59:59 actually occurs twice, though the
2703             UTC time continues to move forward.
2704              
2705             If you specify an ambiguous time, then the latest UTC time is always used, in
2706             effect always choosing standard time. In this case, you can simply subtract an
2707             hour from the object in order to move to saving time, for example:
2708              
2709             # This object represent 01:30:00 standard time
2710             my $dt = DateTime->new(
2711             year => 2003,
2712             month => 10,
2713             day => 26,
2714             hour => 1,
2715             minute => 30,
2716             second => 0,
2717             time_zone => 'America/Chicago',
2718             );
2719              
2720             print $dt->hms; # prints 01:30:00
2721              
2722             # Now the object represent 01:30:00 saving time
2723             $dt->subtract( hours => 1 );
2724              
2725             print $dt->hms; # still prints 01:30:00
2726              
2727             Alternately, you could create the object with the UTC time zone and then call
2728             the C<set_time_zone> method to change the time zone. This is a good way to
2729             ensure that the time is not ambiguous.
2730              
2731             =head4 Invalid Local Times
2732              
2733             Another problem introduced by Daylight Saving Time is that certain local times
2734             just do not exist. For example, in the US in 2003, the transition from standard
2735             to saving time occurred on April 6, at the change to 2:00:00 local time. The
2736             local clock changed from 01:59:59 (standard time) to 03:00:00 (saving time).
2737             This means that there is no 02:00:00 through 02:59:59 on April 6!
2738              
2739             Attempting to create an invalid time currently causes a fatal error.
2740              
2741             =head3 DateTime->from_epoch( epoch => $epoch, ... )
2742              
2743             This class method can be used to construct a new DateTime object from an epoch
2744             time instead of components. Just as with the C<new> method, it accepts
2745             C<time_zone>, C<locale>, and C<formatter> parameters.
2746              
2747             You can also call it with a single unnamed argument, which will be treated as
2748             the epoch value.
2749              
2750             If the epoch value is a non-integral value, it will be rounded to nearest
2751             microsecond.
2752              
2753             By default, the returned object will be in the UTC time zone.
2754              
2755             If you pass a C<time_zone>, then this time zone will be applied I<after> the
2756             object is constructed. In other words, the epoch value is always interpreted as
2757             being in the UTC time zone. Here's an example:
2758              
2759             my $dt = DateTime->from_epoch(
2760             epoch => 0,
2761             time_zone => 'Asia/Tokyo'
2762             );
2763             say $dt; # Prints 1970-01-01T09:00:00 as Asia/Tokyo is +09:00 from UTC.
2764             $dt->set_time_zone('UTC');
2765             say $dt; # Prints 1970-01-01T00:00:00
2766              
2767             =head3 DateTime->now( ... )
2768              
2769             This class method is equivalent to calling C<from_epoch> with the value
2770             returned from Perl's C<time> function. Just as with the C<new> method, it
2771             accepts C<time_zone> and C<locale> parameters.
2772              
2773             By default, the returned object will be in the UTC time zone.
2774              
2775             If you want sub-second resolution, use the L<DateTime::HiRes> module's C<<
2776             DateTime::HiRes->now >> method instead.
2777              
2778             =head3 DateTime->today( ... )
2779              
2780             This class method is equivalent to:
2781              
2782             DateTime->now(@_)->truncate( to => 'day' );
2783              
2784             =head3 DateTime->last_day_of_month( ... )
2785              
2786             This constructor takes the same arguments as can be given to the C<new> method,
2787             except for C<day>. Additionally, both C<year> and C<month> are required.
2788              
2789             =head3 DateTime->from_day_of_year( ... )
2790              
2791             This constructor takes the same arguments as can be given to the C<new> method,
2792             except that it does not accept a C<month> or C<day> argument. Instead, it
2793             requires both C<year> and C<day_of_year>. The day of year must be between 1 and
2794             366, and 366 is only allowed for leap years.
2795              
2796             =head3 DateTime->from_object( object => $object, ... )
2797              
2798             This class method can be used to construct a new DateTime object from any
2799             object that implements the C<utc_rd_values> method. All C<DateTime::Calendar>
2800             modules must implement this method in order to provide cross-calendar
2801             compatibility. This method accepts a C<locale> and C<formatter> parameter
2802              
2803             If the object passed to this method has a C<time_zone> method, that is used to
2804             set the time zone of the newly created C<DateTime> object.
2805              
2806             Otherwise, the returned object will be in the floating time zone.
2807              
2808             =head3 $dt->clone
2809              
2810             This object method returns a new object that is replica of the object upon
2811             which the method is called.
2812              
2813             =head2 "Get" Methods
2814              
2815             This class has many methods for retrieving information about an object.
2816              
2817             =head3 $dt->year
2818              
2819             Returns the year.
2820              
2821             =head3 $dt->ce_year
2822              
2823             Returns the year according to the BCE/CE numbering system. The year before year
2824             1 in this system is year -1, aka "1 BCE".
2825              
2826             =head3 $dt->era_name
2827              
2828             Returns the long name of the current era, something like "Before Christ". See
2829             the L</Locales> section for more details.
2830              
2831             =head3 $dt->era_abbr
2832              
2833             Returns the abbreviated name of the current era, something like "BC". See the
2834             L</Locales> section for more details.
2835              
2836             =head3 $dt->christian_era
2837              
2838             Returns a string, either "BC" or "AD", according to the year.
2839              
2840             =head3 $dt->secular_era
2841              
2842             Returns a string, either "BCE" or "CE", according to the year.
2843              
2844             =head3 $dt->year_with_era
2845              
2846             Returns a string containing the year immediately followed by the appropriate
2847             era abbreviation, based on the object's locale. The year is the absolute value
2848             of C<ce_year>, so that year 1 is "1" and year 0 is "1BC". See the L</Locales>
2849             section for more details.
2850              
2851             =head3 $dt->year_with_christian_era
2852              
2853             Like C<year_with_era>, but uses the C<christian_era> method to get the era
2854             name.
2855              
2856             =head3 $dt->year_with_secular_era
2857              
2858             Like C<year_with_era>, but uses the C<secular_era> method to get the era name.
2859              
2860             =head3 $dt->month
2861              
2862             Returns the month of the year, from 1..12.
2863              
2864             Also available as C<< $dt->mon >>.
2865              
2866             =head3 $dt->month_name
2867              
2868             Returns the name of the current month. See the L</Locales> section for more
2869             details.
2870              
2871             =head3 $dt->month_abbr
2872              
2873             Returns the abbreviated name of the current month. See the L</Locales> section
2874             for more details.
2875              
2876             =head3 $dt->day
2877              
2878             Returns the day of the month, from 1..31.
2879              
2880             Also available as C<< $dt->mday >> and C<< $dt->day_of_month >>.
2881              
2882             =head3 $dt->day_of_week
2883              
2884             Returns the day of the week as a number, from 1..7, with 1 being Monday and 7
2885             being Sunday.
2886              
2887             Also available as C<< $dt->wday >> and C<< $dt->dow >>.
2888              
2889             =head3 $dt->local_day_of_week
2890              
2891             Returns the day of the week as a number, from 1..7. The day corresponding to 1
2892             will vary based on the locale. See the L</Locales> section for more details.
2893              
2894             =head3 $dt->day_name
2895              
2896             Returns the name of the current day of the week. See the L</Locales> section
2897             for more details.
2898              
2899             =head3 $dt->day_abbr
2900              
2901             Returns the abbreviated name of the current day of the week. See the
2902             L</Locales> section for more details.
2903              
2904             =head3 $dt->day_of_year
2905              
2906             Returns the day of the year.
2907              
2908             Also available as C<< $dt->doy >>.
2909              
2910             =head3 $dt->quarter
2911              
2912             Returns the quarter of the year, from 1..4.
2913              
2914             =head3 $dt->quarter_name
2915              
2916             Returns the name of the current quarter. See the L</Locales> section for more
2917             details.
2918              
2919             =head3 $dt->quarter_abbr
2920              
2921             Returns the abbreviated name of the current quarter. See the L</Locales>
2922             section for more details.
2923              
2924             =head3 $dt->day_of_quarter
2925              
2926             Returns the day of the quarter.
2927              
2928             Also available as C<< $dt->doq >>.
2929              
2930             =head3 $dt->weekday_of_month
2931              
2932             Returns a number from 1..5 indicating which week day of the month this is. For
2933             example, June 9, 2003 is the second Monday of the month, and so this method
2934             returns 2 for that date.
2935              
2936             =head3 $dt->ymd($optional_separator), $dt->mdy(...), $dt->dmy(...)
2937              
2938             Each method returns the year, month, and day, in the order indicated by the
2939             method name. Years are zero-padded to four digits. Months and days are 0-padded
2940             to two digits.
2941              
2942             By default, the values are separated by a dash (-), but this can be overridden
2943             by passing a value to the method.
2944              
2945             The C<< $dt->ymd >> method is also available as C<< $dt->date >>.
2946              
2947             =head3 $dt->hour
2948              
2949             Returns the hour of the day, from 0..23.
2950              
2951             =head3 $dt->hour_1
2952              
2953             Returns the hour of the day, from 1..24.
2954              
2955             =head3 $dt->hour_12
2956              
2957             Returns the hour of the day, from 1..12.
2958              
2959             =head3 $dt->hour_12_0
2960              
2961             Returns the hour of the day, from 0..11.
2962              
2963             =head3 $dt->am_or_pm
2964              
2965             Returns the appropriate localized abbreviation, depending on the current hour.
2966              
2967             =head3 $dt->minute
2968              
2969             Returns the minute of the hour, from 0..59.
2970              
2971             Also available as C<< $dt->min >>.
2972              
2973             =head3 $dt->second
2974              
2975             Returns the second, from 0..61. The values 60 and 61 are used for leap seconds.
2976              
2977             Also available as C<< $dt->sec >>.
2978              
2979             =head3 $dt->fractional_second
2980              
2981             Returns the second, as a real number from 0.0 until 61.999999999
2982              
2983             The values 60 and 61 are used for leap seconds.
2984              
2985             =head3 $dt->millisecond
2986              
2987             Returns the fractional part of the second as milliseconds (1E-3 seconds).
2988              
2989             Half a second is 500 milliseconds.
2990              
2991             This value will always be rounded down to the nearest integer.
2992              
2993             =head3 $dt->microsecond
2994              
2995             Returns the fractional part of the second as microseconds (1E-6 seconds).
2996              
2997             Half a second is 500,000 microseconds.
2998              
2999             This value will always be rounded down to the nearest integer.
3000              
3001             =head3 $dt->nanosecond
3002              
3003             Returns the fractional part of the second as nanoseconds (1E-9 seconds).
3004              
3005             Half a second is 500,000,000 nanoseconds.
3006              
3007             =head3 $dt->hms($optional_separator)
3008              
3009             Returns the hour, minute, and second, all zero-padded to two digits. If no
3010             separator is specified, a colon (:) is used by default.
3011              
3012             Also available as C<< $dt->time >>.
3013              
3014             =head3 $dt->datetime($optional_separator)
3015              
3016             This method is equivalent to:
3017              
3018             $dt->ymd('-') . 'T' . $dt->hms(':')
3019              
3020             The C<$optional_separator> parameter allows you to override the separator
3021             between the date and time, for e.g. C<< $dt->datetime(q{ }) >>.
3022              
3023             This method is also available as C<< $dt->iso8601 >>, but it's not really a
3024             very good ISO8601 format, as it lacks a time zone. If called as C<<
3025             $dt->iso8601 >> you cannot change the separator, as ISO8601 specifies that "T"
3026             must be used to separate them.
3027              
3028             =head3 $dt->rfc3339
3029              
3030             This formats a datetime in RFC3339 format. This is the same as C<<
3031             $dt->datetime >> with an added offset at the end of the string except if the
3032             time zone is the floating time zone.
3033              
3034             If the offset is '+00:00' then this is represented as 'Z'. Otherwise the offset
3035             is formatted with a leading sign (+/-) and a colon separated numeric offset
3036             with hours and minutes. If the offset has a non-zero seconds component, that is
3037             also included.
3038              
3039             =head3 $dt->stringify
3040              
3041             This method returns a stringified version of the object. It is also how
3042             stringification overloading is implemented. If the object has a formatter, then
3043             its C<format_datetime> method is used to produce a string. Otherwise, this
3044             method calls C<< $dt->iso8601 >> to produce a string. See L</Formatters And
3045             Stringification> for details.
3046              
3047             =head3 $dt->is_leap_year
3048              
3049             This method returns a boolean value indicating whether or not the datetime
3050             object is in a leap year.
3051              
3052             =head3 $dt->is_last_day_of_month
3053              
3054             This method returns a boolean value indicating whether or not the datetime
3055             object is the last day of the month.
3056              
3057             =head3 $dt->is_last_day_of_quarter
3058              
3059             This method returns a boolean value indicating whether or not the datetime
3060             object is the last day of the quarter.
3061              
3062             =head3 $dt->is_last_day_of_year
3063              
3064             This method returns a boolean value indicating whether or not the datetime
3065             object is the last day of the year.
3066              
3067             =head3 $dt->month_length
3068              
3069             This method returns the number of days in the current month.
3070              
3071             =head3 $dt->quarter_length
3072              
3073             This method returns the number of days in the current quarter.
3074              
3075             =head3 $dt->year_length
3076              
3077             This method returns the number of days in the current year.
3078              
3079             =head3 $dt->week
3080              
3081             my ( $week_year, $week_number ) = $dt->week;
3082              
3083             Returns information about the calendar week for the date. The values returned
3084             by this method are also available separately through the C<< $dt->week_year >>
3085             and C<< $dt->week_number >> methods.
3086              
3087             The first week of the year is defined by ISO as the one which contains the
3088             fourth day of January, which is equivalent to saying that it's the first week
3089             to overlap the new year by at least four days.
3090              
3091             Typically the week year will be the same as the year that the object is in, but
3092             dates at the very beginning of a calendar year often end up in the last week of
3093             the prior year, and similarly, the final few days of the year may be placed in
3094             the first week of the next year.
3095              
3096             =head3 $dt->week_year
3097              
3098             Returns the year of the week. See C<< $dt->week >> for details.
3099              
3100             =head3 $dt->week_number
3101              
3102             Returns the week of the year, from 1..53. See C<< $dt->week >> for details.
3103              
3104             =head3 $dt->week_of_month
3105              
3106             The week of the month, from 0..5. The first week of the month is the first week
3107             that contains a Thursday. This is based on the ICU definition of week of month,
3108             and correlates to the ISO8601 week of year definition. A day in the week
3109             I<before> the week with the first Thursday will be week 0.
3110              
3111             =head3 $dt->jd, $dt->mjd
3112              
3113             These return the Julian Day and Modified Julian Day, respectively. The value
3114             returned is a floating point number. The fractional portion of the number
3115             represents the time portion of the datetime.
3116              
3117             The Julian Day is a count of days since the beginning of the Julian Period,
3118             which starts with day 0 at noon on January 1, -4712.
3119              
3120             The Modified Julian Day is a count of days since midnight on November 17, 1858.
3121              
3122             These methods always refer to the local time, so the Julian Day is the same for
3123             a given datetime regardless of its time zone. Or in other words,
3124             2020-12-04T13:01:57 in "America/Chicago" has the same Julian Day as
3125             2020-12-04T13:01:57 in "Asia/Taipei".
3126              
3127             =head3 $dt->time_zone
3128              
3129             This returns the L<DateTime::TimeZone> object for the datetime object.
3130              
3131             =head3 $dt->offset
3132              
3133             This returns the offset from UTC, in seconds, of the datetime object's time
3134             zone.
3135              
3136             =head3 $dt->is_dst
3137              
3138             Returns a boolean indicating whether or not the datetime's time zone is
3139             currently in Daylight Saving Time or not.
3140              
3141             =head3 $dt->time_zone_long_name
3142              
3143             This is a shortcut for C<< $dt->time_zone->name >>. It's provided so that one
3144             can use "%{time_zone_long_name}" as a strftime format specifier.
3145              
3146             =head3 $dt->time_zone_short_name
3147              
3148             This method returns the time zone abbreviation for the current time zone, such
3149             as "PST" or "GMT". These names are B<not> definitive, and should not be used in
3150             any application intended for general use by users around the world. That's
3151             because it's possible for multiple time zones to have the same abbreviation.
3152              
3153             =head3 $dt->strftime( $format, ... )
3154              
3155             This method implements functionality similar to the C<strftime> method in C.
3156             However, if given multiple format strings, then it will return multiple
3157             scalars, one for each format string.
3158              
3159             See the L<strftime Patterns> section for a list of all possible strftime
3160             patterns.
3161              
3162             If you give a pattern that doesn't exist, then it is simply treated as text.
3163              
3164             Note that any deviation from the POSIX standard is probably a bug. DateTime
3165             should match the output of C<POSIX::strftime> for any given pattern.
3166              
3167             =head3 $dt->format_cldr( $format, ... )
3168              
3169             This method implements formatting based on the CLDR date patterns. If given
3170             multiple format strings, then it will return multiple scalars, one for each
3171             format string.
3172              
3173             See the L<CLDR Patterns> section for a list of all possible CLDR patterns.
3174              
3175             If you give a pattern that doesn't exist, then it is simply treated as text.
3176              
3177             =head3 $dt->epoch
3178              
3179             Returns the UTC epoch value for the datetime object. Datetimes before the start
3180             of the epoch will be returned as a negative number.
3181              
3182             The return value from this method is always an integer number of seconds.
3183              
3184             Since the epoch does not account for leap seconds, the epoch time for
3185             1972-12-31T23:59:60 (UTC) is exactly the same as that for 1973-01-01T00:00:00.
3186              
3187             =head3 $dt->hires_epoch
3188              
3189             Returns the epoch as a floating point number. The floating point portion of the
3190             value represents the nanosecond value of the object. This method is provided
3191             for compatibility with the C<Time::HiRes> module.
3192              
3193             Note that this method suffers from the imprecision of floating point numbers,
3194             and the result may end up rounded to an arbitrary degree depending on your
3195             platform.
3196              
3197             my $dt = DateTime->new( year => 2012, nanosecond => 4 );
3198             say $dt->hires_epoch;
3199              
3200             On my system, this simply prints C<1325376000> because adding C<0.000000004> to
3201             C<1325376000> returns C<1325376000>.
3202              
3203             =head3 $dt->is_finite, $dt->is_infinite
3204              
3205             These methods allow you to distinguish normal datetime objects from infinite
3206             ones. Infinite datetime objects are documented in L<DateTime::Infinite>.
3207              
3208             =head3 $dt->utc_rd_values
3209              
3210             Returns the current UTC Rata Die days, seconds, and nanoseconds as a three
3211             element list. This exists primarily to allow other calendar modules to create
3212             objects based on the values provided by this object.
3213              
3214             =head3 $dt->local_rd_values
3215              
3216             Returns the current local Rata Die days, seconds, and nanoseconds as a three
3217             element list. This exists for the benefit of other modules which might want to
3218             use this information for date math, such as L<DateTime::Event::Recurrence>.
3219              
3220             =head3 $dt->leap_seconds
3221              
3222             Returns the number of leap seconds that have happened up to the datetime
3223             represented by the object. For floating datetimes, this always returns 0.
3224              
3225             =head3 $dt->utc_rd_as_seconds
3226              
3227             Returns the current UTC Rata Die days and seconds purely as seconds. This
3228             number ignores any fractional seconds stored in the object, as well as leap
3229             seconds.
3230              
3231             =head3 $dt->locale
3232              
3233             Returns the datetime's L<DateTime::Locale> object.
3234              
3235             =head3 $dt->formatter
3236              
3237             Returns the current formatter object or class. See L<Formatters And
3238             Stringification> for details.
3239              
3240             =head2 "Set" Methods
3241              
3242             The remaining methods provided by C<DateTime>, except where otherwise
3243             specified, return the object itself, thus making method chaining possible. For
3244             example:
3245              
3246             my $dt = DateTime->now->set_time_zone( 'Australia/Sydney' );
3247              
3248             my $first = DateTime
3249             ->last_day_of_month( year => 2003, month => 3 )
3250             ->add( days => 1 )
3251             ->subtract( seconds => 1 );
3252              
3253             =head3 $dt->set( .. )
3254              
3255             This method can be used to change the local components of a date time. This
3256             method accepts any parameter allowed by the C<new> method except for C<locale>
3257             or C<time_zone>. Use C<set_locale> and C<set_time_zone> for those instead.
3258              
3259             This method performs parameter validation just like the C<new> method.
3260              
3261             B<Do not use this method to do date math. Use the C<add> and C<subtract>
3262             methods instead.>
3263              
3264             =head3 $dt->set_year, $dt->set_month, etc.
3265              
3266             DateTime has a C<set_*> method for every item that can be passed to the
3267             constructor:
3268              
3269             =over 4
3270              
3271             =item * $dt->set_year
3272              
3273             =item * $dt->set_month
3274              
3275             =item * $dt->set_day
3276              
3277             =item * $dt->set_hour
3278              
3279             =item * $dt->set_minute
3280              
3281             =item * $dt->set_second
3282              
3283             =item * $dt->set_nanosecond
3284              
3285             =back
3286              
3287             These are shortcuts to calling C<set> with a single key. They all take a single
3288             parameter.
3289              
3290             =head3 $dt->truncate( to => ... )
3291              
3292             This method allows you to reset some of the local time components in the object
3293             to their "zero" values. The C<to> parameter is used to specify which values to
3294             truncate, and it may be one of C<"year">, C<"quarter">, C<"month">, C<"week">,
3295             C<"local_week">, C<"day">, C<"hour">, C<"minute">, or C<"second">.
3296              
3297             For example, if C<"month"> is specified, then the local day becomes 1, and the
3298             hour, minute, and second all become 0.
3299              
3300             If C<"week"> is given, then the datetime is set to the Monday of the week in
3301             which it occurs, and the time components are all set to 0. If you truncate to
3302             C<"local_week">, then the first day of the week is locale-dependent. For
3303             example, in the C<"en-US"> locale, the first day of the week is Sunday.
3304              
3305             =head3 $dt->set_locale($locale)
3306              
3307             Sets the object's locale. You can provide either a locale code like C<"en-US">
3308             or an object returned by C<< DateTime::Locale->load >>.
3309              
3310             =head3 $dt->set_time_zone($tz)
3311              
3312             This method accepts either a time zone object or a string that can be passed as
3313             the C<name> parameter to C<< DateTime::TimeZone->new >>. If the new time zone's
3314             offset is different from the old time zone, then the I<local> time is adjusted
3315             accordingly.
3316              
3317             For example:
3318              
3319             my $dt = DateTime->new(
3320             year => 2000,
3321             month => 5,
3322             day => 10,
3323             hour => 15,
3324             minute => 15,
3325             time_zone => 'America/Los_Angeles',
3326             );
3327              
3328             print $dt->hour; # prints 15
3329              
3330             $dt->set_time_zone('America/Chicago');
3331              
3332             print $dt->hour; # prints 17
3333              
3334             If the old time zone was a floating time zone, then no adjustments to the local
3335             time are made, except to account for leap seconds. If the new time zone is
3336             floating, then the I<UTC> time is adjusted in order to leave the local time
3337             untouched.
3338              
3339             Fans of Tsai Ming-Liang's films will be happy to know that this does work:
3340              
3341             my $dt = DateTime->now( time_zone => 'Asia/Taipei' );
3342             $dt->set_time_zone('Europe/Paris');
3343              
3344             Yes, now we can know "ni3 na4 bian1 ji2 dian3?"
3345              
3346             =head3 $dt->set_formatter($formatter)
3347              
3348             Sets the formatter for the object. See L<Formatters And Stringification> for
3349             details.
3350              
3351             You can set this to C<undef> to revert to the default formatter.
3352              
3353             =head2 Math Methods
3354              
3355             Like the set methods, math related methods always return the object itself, to
3356             allow for chaining:
3357              
3358             $dt->add( days => 1 )->subtract( seconds => 1 );
3359              
3360             =head3 $dt->duration_class
3361              
3362             This returns L<C<"DateTime::Duration">|DateTime::Duration>, but exists so that
3363             a subclass of C<DateTime> can provide a different value.
3364              
3365             =head3 $dt->add_duration($duration_object)
3366              
3367             This method adds a L<DateTime::Duration> to the current datetime. See the
3368             L<DateTime::Duration> docs for more details.
3369              
3370             =head3 $dt->add( parameters for DateTime::Duration )
3371              
3372             This method is syntactic sugar around the C<< $dt->add_duration >> method. It
3373             simply creates a new L<DateTime::Duration> object using the parameters given,
3374             and then calls the C<< $dt->add_duration >> method.
3375              
3376             =head3 $dt->add($duration_object)
3377              
3378             A synonym of C<< $dt->add_duration($duration_object) >>.
3379              
3380             =head3 $dt->subtract_duration($duration_object)
3381              
3382             When given a L<DateTime::Duration> object, this method simply calls C<<
3383             $dur->inverse >> on that object and passes that new duration to the C<<
3384             $self->add_duration >> method.
3385              
3386             =head3 $dt->subtract( DateTime::Duration->new parameters )
3387              
3388             Like C<< $dt->add >>, this is syntactic sugar for the C<<
3389             $dt->subtract_duration >> method.
3390              
3391             =head3 $dt->subtract($duration_object)
3392              
3393             A synonym of C<< $dt->subtract_duration($duration_object) >>.
3394              
3395             =head3 $dt->subtract_datetime($datetime)
3396              
3397             This method returns a new L<DateTime::Duration> object representing the
3398             difference between the two dates. The duration is B<relative> to the object
3399             from which C<$datetime> is subtracted. For example:
3400              
3401             2003-03-15 00:00:00.00000000
3402             - 2003-02-15 00:00:00.00000000
3403             -------------------------------
3404             = 1 month
3405              
3406             Note that this duration is not an absolute measure of the amount of time
3407             between the two datetimes, because the length of a month varies, as well as due
3408             to the presence of leap seconds.
3409              
3410             The returned duration may have deltas for months, days, minutes, seconds, and
3411             nanoseconds.
3412              
3413             =head3 $dt->delta_md($datetime), $dt->delta_days($datetime)
3414              
3415             Each of these methods returns a new L<DateTime::Duration> object representing
3416             some portion of the difference between two datetimes. The C<< $dt->delta_md >>
3417             method returns a duration which contains only the month and day portions of the
3418             duration is represented. The C<< $dt->delta_days >> method returns a duration
3419             which contains only days.
3420              
3421             The C<< $dt->delta_md >> and C<< $dt->delta_days >> methods truncate the
3422             duration so that any fractional portion of a day is ignored. Both of these
3423             methods operate on the date portion of a datetime only, and so effectively
3424             ignore the time zone.
3425              
3426             Unlike the subtraction methods, B<these methods always return a positive (or
3427             zero) duration>.
3428              
3429             =head3 $dt->delta_ms($datetime)
3430              
3431             Returns a duration which contains only minutes and seconds. Any day and month
3432             differences are converted to minutes and seconds. This method B<always returns
3433             a positive (or zero) duration>.
3434              
3435             =head3 $dt->subtract_datetime_absolute($datetime)
3436              
3437             This method returns a new L<DateTime::Duration> object representing the
3438             difference between the two dates in seconds and nanoseconds. This is the only
3439             way to accurately measure the absolute amount of time between two datetimes,
3440             since units larger than a second do not represent a fixed number of seconds.
3441              
3442             Note that because of leap seconds, this may not return the same result as doing
3443             this math based on the value returned by C<< $dt->epoch >>.
3444              
3445             =head3 $dt->is_between( $lower, $upper )
3446              
3447             Checks whether C<$dt> is strictly between two other DateTime objects.
3448              
3449             "Strictly" means that C<$dt> must be greater than C<$lower> and less than
3450             C<$upper>. If it is I<equal> to either object then this method returns false.
3451              
3452             =head2 Class Methods
3453              
3454             =head3 DateTime->DefaultLocale($locale)
3455              
3456             This can be used to specify the default locale to be used when creating
3457             DateTime objects. If unset, then C<"en-US"> is used.
3458              
3459             This exists for backwards compatibility, but is probably best avoided. This
3460             will change the default locale for every C<DateTime> object created in your
3461             application, even those created by third party libraries which also use
3462             C<DateTime>.
3463              
3464             =head3 DateTime->compare( $dt1, $dt2 ), DateTime->compare_ignore_floating( $dt1, $dt2 )
3465              
3466             $cmp = DateTime->compare( $dt1, $dt2 );
3467              
3468             $cmp = DateTime->compare_ignore_floating( $dt1, $dt2 );
3469              
3470             This method compare two DateTime objects. The semantics are compatible with
3471             Perl's C<sort> function; it returns C<-1> if C<< $dt1 < $dt2 >>, C<0> if C<$dt1
3472             == $dt2>, C<1> if C<< $dt1 > $dt2 >>.
3473              
3474             If one of the two DateTime objects has a floating time zone, it will first be
3475             converted to the time zone of the other object. This is what you want most of
3476             the time, but it can lead to inconsistent results when you compare a number of
3477             DateTime objects, some of which are floating, and some of which are in other
3478             time zones.
3479              
3480             If you want to have consistent results (because you want to sort an array of
3481             objects, for example), you can use the C<compare_ignore_floating> method:
3482              
3483             @dates = sort { DateTime->compare_ignore_floating( $a, $b ) } @dates;
3484              
3485             In this case, objects with a floating time zone will be sorted as if they were
3486             UTC times.
3487              
3488             Since DateTime objects overload comparison operators, this:
3489              
3490             @dates = sort @dates;
3491              
3492             is equivalent to this:
3493              
3494             @dates = sort { DateTime->compare( $a, $b ) } @dates;
3495              
3496             DateTime objects can be compared to any other calendar class that implements
3497             the C<utc_rd_values> method.
3498              
3499             =head2 Testing Code That Uses DateTime
3500              
3501             If you are trying to test code that calls uses DateTime, you may want to be to
3502             explicitly set the value returned by Perl's C<time> builtin. This builtin is
3503             called by C<< DateTime->now >> and C<< DateTime->today >>.
3504              
3505             You can override C<CORE::GLOBAL::time>, but this will only work if you do this
3506             B<before> loading DateTime. If doing this is inconvenient, you can also
3507             override C<DateTime::_core_time>:
3508              
3509             no warnings 'redefine';
3510             local *DateTime::_core_time = sub { return 42 };
3511              
3512             DateTime is guaranteed to call this subroutine to get the current C<time>
3513             value. You can also override the C<_core_time> sub in a subclass of DateTime
3514             and use that.
3515              
3516             =head2 How DateTime Math Works
3517              
3518             It's important to have some understanding of how datetime math is implemented
3519             in order to effectively use this module and L<DateTime::Duration>.
3520              
3521             =head3 Making Things Simple
3522              
3523             If you want to simplify your life and not have to think too hard about the
3524             nitty-gritty of datetime math, I have several recommendations:
3525              
3526             =over 4
3527              
3528             =item * use the floating time zone
3529              
3530             If you do not care about time zones or leap seconds, use the "floating"
3531             timezone:
3532              
3533             my $dt = DateTime->now( time_zone => 'floating' );
3534              
3535             Math done on two objects in the floating time zone produces very predictable
3536             results.
3537              
3538             Note that in most cases you will want to start by creating an object in a
3539             specific zone and I<then> convert it to the floating time zone. When an object
3540             goes from a real zone to the floating zone, the time for the object remains the
3541             same.
3542              
3543             This means that passing the floating zone to a constructor may not do what you
3544             want.
3545              
3546             my $dt = DateTime->now( time_zone => 'floating' );
3547              
3548             is equivalent to
3549              
3550             my $dt = DateTime->now( time_zone => 'UTC' )->set_time_zone('floating');
3551              
3552             This might not be what you wanted. Instead, you may prefer to do this:
3553              
3554             my $dt = DateTime->now( time_zone => 'local' )->set_time_zone('floating');
3555              
3556             =item * use UTC for all calculations
3557              
3558             If you do care about time zones (particularly DST) or leap seconds, try to use
3559             non-UTC time zones for presentation and user input only. Convert to UTC
3560             immediately and convert back to the local time zone for presentation:
3561              
3562             my $dt = DateTime->new( %user_input, time_zone => $user_tz );
3563             $dt->set_time_zone('UTC');
3564              
3565             # do various operations - store it, retrieve it, add, subtract, etc.
3566              
3567             $dt->set_time_zone($user_tz);
3568             print $dt->datetime;
3569              
3570             =item * math on non-UTC time zones
3571              
3572             If you need to do date math on objects with non-UTC time zones, please read the
3573             caveats below carefully. The results C<DateTime> produces are predictable,
3574             correct, and mostly intuitive, but datetime math gets very ugly when time zones
3575             are involved, and there are a few strange corner cases involving subtraction of
3576             two datetimes across a DST change.
3577              
3578             If you can always use the floating or UTC time zones, you can skip ahead to
3579             L<Leap Seconds and Date Math>
3580              
3581             =item * date vs datetime math
3582              
3583             If you only care about the date (calendar) portion of a datetime, you should
3584             use either C<< $dt->delta_md >> or C<< $dt->delta_days >>, not C<<
3585             $dt->subtract_datetime >>. This will give predictable, unsurprising results,
3586             free from DST-related complications.
3587              
3588             =item * $dt->subtract_datetime and $dt->add_duration
3589              
3590             You must convert your datetime objects to the UTC time zone before doing date
3591             math if you want to make sure that the following formulas are always true:
3592              
3593             $dt2 - $dt1 = $dur
3594             $dt1 + $dur = $dt2
3595             $dt2 - $dur = $dt1
3596              
3597             Note that using C<< $dt->delta_days >> ensures that this formula always works,
3598             regardless of the time zones of the objects involved, as does using C<<
3599             $dt->subtract_datetime_absolute >>. Other methods of subtraction are not always
3600             reversible.
3601              
3602             =item * never do math on two objects where only one is in the floating time zone
3603              
3604             The date math code accounts for leap seconds whenever the C<DateTime> object is
3605             not in the floating time zone. If you try to do math where one object is in the
3606             floating zone and the other isn't, the results will be confusing and wrong.
3607              
3608             =back
3609              
3610             =head3 Adding a Duration to a DateTime
3611              
3612             The parts of a duration can be broken down into five parts. These are months,
3613             days, minutes, seconds, and nanoseconds. Adding one month to a date is
3614             different than adding 4 weeks or 28, 29, 30, or 31 days. Similarly, due to DST
3615             and leap seconds, adding a day can be different than adding 86,400 seconds, and
3616             adding a minute is not exactly the same as 60 seconds.
3617              
3618             We cannot convert between these units, except for seconds and nanoseconds,
3619             because there is no fixed conversion between most pairs of units. That is
3620             because of things like leap seconds, DST changes, etc.
3621              
3622             C<DateTime> always adds (or subtracts) days, then months, minutes, and then
3623             seconds and nanoseconds. If there are any boundary overflows, these are
3624             normalized at each step. For the days and months the local (not UTC) values are
3625             used. For minutes and seconds, the local values are used. This generally just
3626             works.
3627              
3628             This means that adding one month and one day to February 28, 2003 will produce
3629             the date April 1, 2003, not March 29, 2003.
3630              
3631             my $dt = DateTime->new( year => 2003, month => 2, day => 28 );
3632              
3633             $dt->add( months => 1, days => 1 );
3634              
3635             # 2003-04-01 - the result
3636              
3637             On the other hand, if we add months first, and then separately add days, we end
3638             up with March 29, 2003:
3639              
3640             $dt->add( months => 1 )->add( days => 1 );
3641              
3642             # 2003-03-29
3643              
3644             We see similar strangeness when math crosses a DST boundary:
3645              
3646             my $dt = DateTime->new(
3647             year => 2003,
3648             month => 4,
3649             day => 5,
3650             hour => 1,
3651             minute => 58,
3652             time_zone => "America/Chicago",
3653             );
3654              
3655             $dt->add( days => 1, minutes => 3 );
3656             # 2003-04-06 02:01:00
3657              
3658             $dt->add( minutes => 3 )->add( days => 1 );
3659             # 2003-04-06 03:01:00
3660              
3661             Note that if you converted the datetime object to UTC first you would get
3662             predictable results.
3663              
3664             If you want to know how many seconds a L<DateTime::Duration> object represents,
3665             you have to add it to a datetime to find out, so you could do:
3666              
3667             my $now = DateTime->now( time_zone => 'UTC' );
3668             my $later = $now->clone->add_duration($duration);
3669              
3670             my $seconds_dur = $later->subtract_datetime_absolute($now);
3671              
3672             This returns a L<DateTime::Duration> which only contains seconds and
3673             nanoseconds.
3674              
3675             If we were add the duration to a different C<DateTime> object we might get a
3676             different number of seconds.
3677              
3678             L<DateTime::Duration> supports three different end-of-month algorithms for
3679             adding months. This comes into play when an addition results in a day past the
3680             end of the following month (for example, adding one month to January 30).
3681              
3682             # 2010-08-31 + 1 month = 2010-10-01
3683             $dt->add( months => 1, end_of_month => 'wrap' );
3684              
3685             # 2010-01-30 + 1 month = 2010-02-28
3686             $dt->add( months => 1, end_of_month => 'limit' );
3687              
3688             # 2010-04-30 + 1 month = 2010-05-31
3689             $dt->add( months => 1, end_of_month => 'preserve' );
3690              
3691             By default, it uses C<"wrap"> for positive durations and C<"preserve"> for
3692             negative durations. See L<DateTime::Duration> for a detailed explanation of
3693             these algorithms.
3694              
3695             If you need to do lots of work with durations, take a look at the
3696             L<DateTime::Format::Duration> module, which lets you present information from
3697             durations in many useful ways.
3698              
3699             There are other subtract/delta methods in C<DateTime> to generate different
3700             types of durations. These methods are C<< $dt->subtract_datetime >>, C<<
3701             $dt->subtract_datetime_absolute >>, C<< $dt->delta_md >>, C<< $dt->delta_days
3702             >>, and C<< $dt->delta_ms >>.
3703              
3704             =head3 DateTime Subtraction
3705              
3706             Date subtraction is done based solely on the two object's local datetimes, with
3707             one exception to handle DST changes. Also, if the two datetime objects are in
3708             different time zones, one of them is converted to the other's time zone first
3709             before subtraction. This is best explained through examples:
3710              
3711             The first of these probably makes the most sense:
3712              
3713             # not DST
3714             my $dt1 = DateTime->new(
3715             year => 2003,
3716             month => 5,
3717             day => 6,
3718             time_zone => 'America/Chicago',
3719             );
3720              
3721             # is DST
3722             my $dt2 = DateTime->new(
3723             year => 2003,
3724             month => 11,
3725             day => 6,
3726             time_zone => 'America/Chicago',
3727             );
3728              
3729             # 6 months
3730             my $dur = $dt2->subtract_datetime($dt1);
3731              
3732             Nice and simple.
3733              
3734             This one is a little trickier, but still fairly logical:
3735              
3736             # is DST
3737             my $dt1 = DateTime->new(
3738             year => 2003,
3739             month => 4,
3740             day => 5,
3741             hour => 1,
3742             minute => 58,
3743             time_zone => "America/Chicago",
3744             );
3745              
3746             # not DST
3747             my $dt2 = DateTime->new(
3748             year => 2003,
3749             month => 4,
3750             day => 7,
3751             hour => 2,
3752             minute => 1,
3753             time_zone => "America/Chicago",
3754             );
3755              
3756             # 2 days and 3 minutes
3757             my $dur = $dt2->subtract_datetime($dt1);
3758              
3759             Which contradicts the result this one gives, even though they both make sense:
3760              
3761             # is DST
3762             my $dt1 = DateTime->new(
3763             year => 2003,
3764             month => 4,
3765             day => 5,
3766             hour => 1,
3767             minute => 58,
3768             time_zone => "America/Chicago",
3769             );
3770              
3771             # not DST
3772             my $dt2 = DateTime->new(
3773             year => 2003,
3774             month => 4,
3775             day => 6,
3776             hour => 3,
3777             minute => 1,
3778             time_zone => "America/Chicago",
3779             );
3780              
3781             # 1 day and 3 minutes
3782             my $dur = $dt2->subtract_datetime($dt1);
3783              
3784             This last example illustrates the "DST" exception mentioned earlier. The
3785             exception accounts for the fact 2003-04-06 only lasts 23 hours.
3786              
3787             And finally:
3788              
3789             my $dt2 = DateTime->new(
3790             year => 2003,
3791             month => 10,
3792             day => 26,
3793             hour => 1,
3794             time_zone => 'America/Chicago',
3795             );
3796              
3797             my $dt1 = $dt2->clone->subtract( hours => 1 );
3798              
3799             # 60 minutes
3800             my $dur = $dt2->subtract_datetime($dt1);
3801              
3802             This seems obvious until you realize that subtracting 60 minutes from C<$dt2>
3803             in the above example still leaves the clock time at "01:00:00". This time we
3804             are accounting for a 25 hour day.
3805              
3806             =head3 Reversibility
3807              
3808             Date math operations are not always reversible. This is because of the way that
3809             addition operations are ordered. As was discussed earlier, adding 1 day and 3
3810             minutes in one call to C<< $dt->add >> is not the same as first adding 3
3811             minutes and 1 day in two separate calls.
3812              
3813             If we take a duration returned from C<< $dt->subtract_datetime >> and then try
3814             to add or subtract that duration from one of the datetimes we just used, we
3815             sometimes get interesting results:
3816              
3817             my $dt1 = DateTime->new(
3818             year => 2003,
3819             month => 4,
3820             day => 5,
3821             hour => 1,
3822             minute => 58,
3823             time_zone => "America/Chicago",
3824             );
3825              
3826             my $dt2 = DateTime->new(
3827             year => 2003,
3828             month => 4,
3829             day => 6,
3830             hour => 3,
3831             minute => 1,
3832             time_zone => "America/Chicago",
3833             );
3834              
3835             # 1 day and 3 minutes
3836             my $dur = $dt2->subtract_datetime($dt1);
3837              
3838             # gives us $dt2
3839             $dt1->add_duration($dur);
3840              
3841             # gives us 2003-04-05 02:58:00 - 1 hour later than $dt1
3842             $dt2->subtract_duration($dur);
3843              
3844             The C<< $dt->subtract_duration >> operation gives us a (perhaps) unexpected
3845             answer because it first subtracts one day to get 2003-04-05T03:01:00 and then
3846             subtracts 3 minutes to get the final result.
3847              
3848             If we explicitly reverse the order we can get the original value of C<$dt1>.
3849             This can be facilitated by the L<DateTime::Duration> class's C<<
3850             $dur->calendar_duration >> and C<< $dur->clock_duration >> methods:
3851              
3852             $dt2->subtract_duration( $dur->clock_duration )
3853             ->subtract_duration( $dur->calendar_duration );
3854              
3855             =head3 Leap Seconds and Date Math
3856              
3857             The presence of leap seconds can cause even more anomalies in date math. For
3858             example, the following is a legal datetime:
3859              
3860             my $dt = DateTime->new(
3861             year => 1972,
3862             month => 12,
3863             day => 31,
3864             hour => 23,
3865             minute => 59,
3866             second => 60,
3867             time_zone => 'UTC'
3868             );
3869              
3870             If we add one month ...
3871              
3872             $dt->add( months => 1 );
3873              
3874             ... the datetime is now "1973-02-01 00:00:00", because there is no 23:59:60 on
3875             1973-01-31.
3876              
3877             Leap seconds also force us to distinguish between minutes and seconds during
3878             date math. Given the following datetime ...
3879              
3880             my $dt = DateTime->new(
3881             year => 1972,
3882             month => 12,
3883             day => 31,
3884             hour => 23,
3885             minute => 59,
3886             second => 30,
3887             time_zone => 'UTC'
3888             );
3889              
3890             ... we will get different results when adding 1 minute than we get if we add 60
3891             seconds. This is because in this case, the last minute of the day, beginning at
3892             23:59:00, actually contains 61 seconds.
3893              
3894             Here are the results we get:
3895              
3896             # 1972-12-31 23:59:30 - our starting datetime
3897             my $dt = DateTime->new(
3898             year => 1972,
3899             month => 12,
3900             day => 31,
3901             hour => 23,
3902             minute => 59,
3903             second => 30,
3904             time_zone => 'UTC'
3905             );
3906              
3907             # 1973-01-01 00:00:30 - one minute later
3908             $dt->clone->add( minutes => 1 );
3909              
3910             # 1973-01-01 00:00:29 - 60 seconds later
3911             $dt->clone->add( seconds => 60 );
3912              
3913             # 1973-01-01 00:00:30 - 61 seconds later
3914             $dt->clone->add( seconds => 61 );
3915              
3916             =head3 Local vs. UTC and 24 hours vs. 1 day
3917              
3918             When math crosses a daylight saving boundary, a single day may have more or
3919             less than 24 hours.
3920              
3921             For example, if you do this ...
3922              
3923             my $dt = DateTime->new(
3924             year => 2003,
3925             month => 4,
3926             day => 5,
3927             hour => 2,
3928             time_zone => 'America/Chicago',
3929             );
3930              
3931             $dt->add( days => 1 );
3932              
3933             ... then you will produce an I<invalid> local time, and therefore an exception
3934             will be thrown.
3935              
3936             However, this works ...
3937              
3938             my $dt = DateTime->new(
3939             year => 2003,
3940             month => 4,
3941             day => 5,
3942             hour => 2,
3943             time_zone => 'America/Chicago',
3944             );
3945              
3946             $dt->add( hours => 24 );
3947              
3948             ... and produces a datetime with the local time of "03:00".
3949              
3950             If all this makes your head hurt, there is a simple alternative. Just convert
3951             your datetime object to the "UTC" time zone before doing date math on it, and
3952             switch it back to the local time zone afterwards. This avoids the possibility
3953             of having date math throw an exception, and makes sure that 1 day equals 24
3954             hours. Of course, this may not always be desirable, so caveat user!
3955              
3956             =head2 Overloading
3957              
3958             This module explicitly overloads the addition (+), subtraction (-), string and
3959             numeric comparison operators. This means that the following all do sensible
3960             things:
3961              
3962             my $new_dt = $dt + $duration_obj;
3963              
3964             my $new_dt = $dt - $duration_obj;
3965              
3966             my $duration_obj = $dt - $new_dt;
3967              
3968             for my $dt ( sort @dts ) {...}
3969              
3970             Additionally, the fallback parameter is set to true, so other derivable
3971             operators (+=, -=, etc.) will work properly. Do not expect increment (++) or
3972             decrement (--) to do anything useful.
3973              
3974             The string comparison operators, C<eq> or C<ne>, will use the string value to
3975             compare with non-DateTime objects.
3976              
3977             DateTime objects do not have a numeric value, using C<==> or C<< <=> >> to
3978             compare a DateTime object with a non-DateTime object will result in an
3979             exception. To safely sort mixed DateTime and non-DateTime objects, use C<sort {
3980             $a cmp $b } @dates>.
3981              
3982             The module also overloads stringification using the object's formatter,
3983             defaulting to C<iso8601> method. See L<Formatters And Stringification> for
3984             details.
3985              
3986             =head2 Formatters And Stringification
3987              
3988             You can optionally specify a C<formatter>, which is usually a
3989             C<DateTime::Format::*> object or class, to control the stringification of the
3990             DateTime object.
3991              
3992             Any of the constructor methods can accept a formatter argument:
3993              
3994             my $formatter = DateTime::Format::Strptime->new(...);
3995             my $dt = DateTime->new( year => 2004, formatter => $formatter );
3996              
3997             Or, you can set it afterwards:
3998              
3999             $dt->set_formatter($formatter);
4000             $formatter = $dt->formatter;
4001              
4002             Once you set the formatter, the overloaded stringification method will use the
4003             formatter. If unspecified, the C<iso8601> method is used.
4004              
4005             A formatter can be handy when you know that in your application you want to
4006             stringify your DateTime objects into a special format all the time, for example
4007             in Postgres format.
4008              
4009             If you provide a formatter class name or object, it must implement a
4010             C<format_datetime> method. This method will be called with just the C<DateTime>
4011             object as its argument.
4012              
4013             =head2 CLDR Patterns
4014              
4015             The CLDR pattern language is both more powerful and more complex than strftime.
4016             Unlike strftime patterns, you often have to explicitly escape text that you do
4017             not want formatted, as the patterns are simply letters without any prefix.
4018              
4019             For example, C<"yyyy-MM-dd"> is a valid CLDR pattern. If you want to include
4020             any lower or upper case ASCII characters as-is, you can surround them with
4021             single quotes ('). If you want to include a single quote, you must escape it as
4022             two single quotes ('').
4023              
4024             my $pattern1 = q{'Today is ' EEEE};
4025             my $pattern2 = q{'It is now' h 'o''clock' a};
4026              
4027             Spaces and any non-letter text will always be passed through as-is.
4028              
4029             Many CLDR patterns which produce numbers will pad the number with leading
4030             zeroes depending on the length of the format specifier. For example, C<"h">
4031             represents the current hour from 1-12. If you specify C<"hh"> then hours 1-9
4032             will have a leading zero prepended.
4033              
4034             However, CLDR often uses five of a letter to represent the narrow form of a
4035             pattern. This inconsistency is necessary for backwards compatibility.
4036              
4037             There are many cases where CLDR patterns distinguish between the "format" and
4038             "stand-alone" forms of a pattern. The format pattern is used when the thing in
4039             question is being placed into a larger string. The stand-alone form is used
4040             when displaying that item by itself, for example in a calendar.
4041              
4042             There are also many cases where CLDR provides three sizes for each item, wide
4043             (the full name), abbreviated, and narrow. The narrow form is often just a
4044             single character, for example "T" for "Tuesday", and may not be unique.
4045              
4046             CLDR provides a fairly complex system for localizing time zones that we ignore
4047             entirely. The time zone patterns just use the information provided by
4048             C<DateTime::TimeZone>, and I<do not follow the CLDR spec>.
4049              
4050             The output of a CLDR pattern is always localized, when applicable.
4051              
4052             CLDR provides the following patterns:
4053              
4054             =over 4
4055              
4056             =item * G{1,3}
4057              
4058             The abbreviated era (BC, AD).
4059              
4060             =item * GGGG
4061              
4062             The wide era (Before Christ, Anno Domini).
4063              
4064             =item * GGGGG
4065              
4066             The narrow era, if it exists (but it mostly doesn't).
4067              
4068             =item * y and y{3,}
4069              
4070             The year, zero-prefixed as needed. Negative years will start with a "-", and
4071             this will be included in the length calculation.
4072              
4073             In other, words the "yyyyy" pattern will format year -1234 as "-1234", not
4074             "-01234".
4075              
4076             =item * yy
4077              
4078             This is a special case. It always produces a two-digit year, so "1976" becomes
4079             "76". Negative years will start with a "-", making them one character longer.
4080              
4081             =item * Y{1,}
4082              
4083             The year in "week of the year" calendars, from C<< $dt->week_year >>.
4084              
4085             =item * u{1,}
4086              
4087             Same as "y" except that "uu" is not a special case.
4088              
4089             =item * Q{1,2}
4090              
4091             The quarter as a number (1..4).
4092              
4093             =item * QQQ
4094              
4095             The abbreviated format form for the quarter.
4096              
4097             =item * QQQQ
4098              
4099             The wide format form for the quarter.
4100              
4101             =item * q{1,2}
4102              
4103             The quarter as a number (1..4).
4104              
4105             =item * qqq
4106              
4107             The abbreviated stand-alone form for the quarter.
4108              
4109             =item * qqqq
4110              
4111             The wide stand-alone form for the quarter.
4112              
4113             =item * M{1,2}
4114              
4115             The numerical month.
4116              
4117             =item * MMM
4118              
4119             The abbreviated format form for the month.
4120              
4121             =item * MMMM
4122              
4123             The wide format form for the month.
4124              
4125             =item * MMMMM
4126              
4127             The narrow format form for the month.
4128              
4129             =item * L{1,2}
4130              
4131             The numerical month.
4132              
4133             =item * LLL
4134              
4135             The abbreviated stand-alone form for the month.
4136              
4137             =item * LLLL
4138              
4139             The wide stand-alone form for the month.
4140              
4141             =item * LLLLL
4142              
4143             The narrow stand-alone form for the month.
4144              
4145             =item * w{1,2}
4146              
4147             The week of the year, from C<< $dt->week_number >>.
4148              
4149             =item * W
4150              
4151             The week of the month, from C<< $dt->week_of_month >>.
4152              
4153             =item * d{1,2}
4154              
4155             The numeric day of the month.
4156              
4157             =item * D{1,3}
4158              
4159             The numeric day of the year.
4160              
4161             =item * F
4162              
4163             The day of the week in the month, from C<< $dt->weekday_of_month >>.
4164              
4165             =item * g{1,}
4166              
4167             The modified Julian day, from C<< $dt->mjd >>.
4168              
4169             =item * E{1,3} and eee
4170              
4171             The abbreviated format form for the day of the week.
4172              
4173             =item * EEEE and eeee
4174              
4175             The wide format form for the day of the week.
4176              
4177             =item * EEEEE and eeeee
4178              
4179             The narrow format form for the day of the week.
4180              
4181             =item * e{1,2}
4182              
4183             The I<local> numeric day of the week, from 1 to 7. This number depends on what
4184             day is considered the first day of the week, which varies by locale. For
4185             example, in the US, Sunday is the first day of the week, so this returns 2 for
4186             Monday.
4187              
4188             =item * c
4189              
4190             The numeric day of the week from 1 to 7, treating Monday as the first of the
4191             week, regardless of locale.
4192              
4193             =item * ccc
4194              
4195             The abbreviated stand-alone form for the day of the week.
4196              
4197             =item * cccc
4198              
4199             The wide stand-alone form for the day of the week.
4200              
4201             =item * ccccc
4202              
4203             The narrow format form for the day of the week.
4204              
4205             =item * a
4206              
4207             The localized form of AM or PM for the time.
4208              
4209             =item * h{1,2}
4210              
4211             The hour from 1-12.
4212              
4213             =item * H{1,2}
4214              
4215             The hour from 0-23.
4216              
4217             =item * K{1,2}
4218              
4219             The hour from 0-11.
4220              
4221             =item * k{1,2}
4222              
4223             The hour from 1-24.
4224              
4225             =item * j{1,2}
4226              
4227             The hour, in 12 or 24 hour form, based on the preferred form for the locale. In
4228             other words, this is equivalent to either "h{1,2}" or "H{1,2}".
4229              
4230             =item * m{1,2}
4231              
4232             The minute.
4233              
4234             =item * s{1,2}
4235              
4236             The second.
4237              
4238             =item * S{1,}
4239              
4240             The fractional portion of the seconds, rounded based on the length of the
4241             specifier. This returned I<without> a leading decimal point, but may have
4242             leading or trailing zeroes.
4243              
4244             =item * A{1,}
4245              
4246             The millisecond of the day, based on the current time. In other words, if it is
4247             12:00:00.00, this returns 43200000.
4248              
4249             =item * z{1,3}
4250              
4251             The time zone short name.
4252              
4253             =item * zzzz
4254              
4255             The time zone long name.
4256              
4257             =item * Z{1,3}
4258              
4259             The time zone offset.
4260              
4261             =item * ZZZZ
4262              
4263             The time zone short name and the offset as one string, so something like
4264             "CDT-0500".
4265              
4266             =item * ZZZZZ
4267              
4268             The time zone offset as a sexagesimal number, so something like "-05:00". (This
4269             is useful for W3C format.)
4270              
4271             =item * v{1,3}
4272              
4273             The time zone short name.
4274              
4275             =item * vvvv
4276              
4277             The time zone long name.
4278              
4279             =item * V{1,3}
4280              
4281             The time zone short name.
4282              
4283             =item * VVVV
4284              
4285             The time zone long name.
4286              
4287             =back
4288              
4289             =head3 CLDR "Available Formats"
4290              
4291             The CLDR data includes pre-defined formats for various patterns such as "month
4292             and day" or "time of day". Using these formats lets you render information
4293             about a datetime in the most natural way for users from a given locale.
4294              
4295             These formats are indexed by a key that is itself a CLDR pattern. When you look
4296             these up, you get back a different CLDR pattern suitable for the locale.
4297              
4298             Let's look at some example We'll use C<2008-02-05T18:30:30> as our example
4299             datetime value, and see how this is rendered for the C<"en-US"> and C<"fr-FR">
4300             locales.
4301              
4302             =over 4
4303              
4304             =item * C<MMMd>
4305              
4306             The abbreviated month and day as number. For C<en-US>, we get the pattern C<MMM
4307             d>, which renders as C<Feb 5>. For C<fr-FR>, we get the pattern C<d MMM>, which
4308             renders as C<5 févr.>.
4309              
4310             =item * C<yQQQ>
4311              
4312             The year and abbreviated quarter of year. For C<en-US>, we get the pattern
4313             C<QQQ y>, which renders as C<Q1 2008>. For C<fr-FR>, we get the same pattern,
4314             C<QQQ y>, which renders as C<T1 2008>.
4315              
4316             =item * C<hm>
4317              
4318             The 12-hour time of day without seconds. For C<en-US>, we get the pattern
4319             C<h:mm a>, which renders as C<6:30 PM>. For C<fr-FR>, we get the exact same
4320             pattern and rendering.
4321              
4322             =back
4323              
4324             The available formats for each locale are documented in the POD for that
4325             locale. To get back the format, you use the C<< $locale->format_for >> method.
4326             For example:
4327              
4328             say $dt->format_cldr( $dt->locale->format_for('MMMd') );
4329              
4330             =head2 strftime Patterns
4331              
4332             The following patterns are allowed in the format string given to the C<<
4333             $dt->strftime >> method:
4334              
4335             =over 4
4336              
4337             =item * %a
4338              
4339             The abbreviated weekday name.
4340              
4341             =item * %A
4342              
4343             The full weekday name.
4344              
4345             =item * %b
4346              
4347             The abbreviated month name.
4348              
4349             =item * %B
4350              
4351             The full month name.
4352              
4353             =item * %c
4354              
4355             The default datetime format for the object's locale.
4356              
4357             =item * %C
4358              
4359             The century number (year/100) as a 2-digit integer.
4360              
4361             =item * %d
4362              
4363             The day of the month as a decimal number (range 01 to 31).
4364              
4365             =item * %D
4366              
4367             Equivalent to %m/%d/%y. This is not a good standard format if you want folks
4368             from both the United States and the rest of the world to understand the date!
4369              
4370             =item * %e
4371              
4372             Like %d, the day of the month as a decimal number, but a leading zero is
4373             replaced by a space.
4374              
4375             =item * %F
4376              
4377             Equivalent to %Y-%m-%d (the ISO 8601 date format)
4378              
4379             =item * %G
4380              
4381             The ISO 8601 year with century as a decimal number. The 4-digit year
4382             corresponding to the ISO week number (see %V). This has the same format and
4383             value as %Y, except that if the ISO week number belongs to the previous or next
4384             year, that year is used instead. (TZ)
4385              
4386             =item * %g
4387              
4388             Like %G, but without century, i.e., with a 2-digit year (00-99).
4389              
4390             =item * %h
4391              
4392             Equivalent to %b.
4393              
4394             =item * %H
4395              
4396             The hour as a decimal number using a 24-hour clock (range 00 to 23).
4397              
4398             =item * %I
4399              
4400             The hour as a decimal number using a 12-hour clock (range 01 to 12).
4401              
4402             =item * %j
4403              
4404             The day of the year as a decimal number (range 001 to 366).
4405              
4406             =item * %k
4407              
4408             The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are
4409             preceded by a blank. (See also %H.)
4410              
4411             =item * %l
4412              
4413             The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are
4414             preceded by a blank. (See also %I.)
4415              
4416             =item * %m
4417              
4418             The month as a decimal number (range 01 to 12).
4419              
4420             =item * %M
4421              
4422             The minute as a decimal number (range 00 to 59).
4423              
4424             =item * %n
4425              
4426             A newline character.
4427              
4428             =item * %N
4429              
4430             The fractional seconds digits. Default is 9 digits (nanoseconds).
4431              
4432             %3N milliseconds (3 digits)
4433             %6N microseconds (6 digits)
4434             %9N nanoseconds (9 digits)
4435              
4436             This value will always be rounded down to the nearest integer.
4437              
4438             =item * %p
4439              
4440             Either `AM' or `PM' according to the given time value, or the corresponding
4441             strings for the current locale. Noon is treated as `pm' and midnight as `am'.
4442              
4443             =item * %P
4444              
4445             Like %p but in lowercase: `am' or `pm' or a corresponding string for the
4446             current locale.
4447              
4448             =item * %r
4449              
4450             The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to
4451             `%I:%M:%S %p'.
4452              
4453             =item * %R
4454              
4455             The time in 24-hour notation (%H:%M). (SU) For a version including the seconds,
4456             see %T below.
4457              
4458             =item * %s
4459              
4460             The number of seconds since the epoch.
4461              
4462             =item * %S
4463              
4464             The second as a decimal number (range 00 to 61).
4465              
4466             =item * %t
4467              
4468             A tab character.
4469              
4470             =item * %T
4471              
4472             The time in 24-hour notation (%H:%M:%S).
4473              
4474             =item * %u
4475              
4476             The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
4477              
4478             =item * %U
4479              
4480             The week number of the current year as a decimal number, range 00 to 53,
4481             starting with the first Sunday as the first day of week 01. See also %V and %W.
4482              
4483             =item * %V
4484              
4485             The ISO 8601:1988 week number of the current year as a decimal number, range 01
4486             to 53, where week 1 is the first week that has at least 4 days in the current
4487             year, and with Monday as the first day of the week. See also %U and %W.
4488              
4489             =item * %w
4490              
4491             The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
4492              
4493             =item * %W
4494              
4495             The week number of the current year as a decimal number, range 00 to 53,
4496             starting with the first Monday as the first day of week 01.
4497              
4498             =item * %x
4499              
4500             The default date format for the object's locale.
4501              
4502             =item * %X
4503              
4504             The default time format for the object's locale.
4505              
4506             =item * %y
4507              
4508             The year as a decimal number without a century (range 00 to 99).
4509              
4510             =item * %Y
4511              
4512             The year as a decimal number including the century.
4513              
4514             =item * %z
4515              
4516             The time-zone as hour offset from UTC. Required to emit RFC822-conformant dates
4517             (using "%a, %d %b %Y %H:%M:%S %z").
4518              
4519             =item * %Z
4520              
4521             The short name for the time zone, typically an abbreviation like "EST" or
4522             "AEST".
4523              
4524             =item * %%
4525              
4526             A literal `%' character.
4527              
4528             =item * %{method}
4529              
4530             Any method name may be specified using the format C<%{method}> name where
4531             "method" is a valid C<DateTime> object method.
4532              
4533             =back
4534              
4535             =head2 DateTime and Storable
4536              
4537             C<DateTime> implements L<Storable> hooks in order to reduce the size of a
4538             serialized C<DateTime> object.
4539              
4540             =head1 DEVELOPMENT TOOLS
4541              
4542             If you're working on the C<DateTIme> code base, there are a few extra non-Perl
4543             tools that you may find useful, notably
4544             L<precious|https://github.com/houseabsolute/precious>, a meta-linter/tidier.
4545             You can install all the necessary tools in C<$HOME/bin> by running
4546             F<./dev-bin/install-dev-tools.sh>.
4547              
4548             Try running C<precious tidy -a> to tidy all the tidyable files in the repo, and
4549             C<precious lint -a> to run all the lint checks.
4550              
4551             You can enable a git pre-commit hook for linting by running F<./git/setup.pl>.
4552              
4553             Note that linting will be checked in CI, and it's okay to submit a PR which
4554             fails the linting check, but it's extra nice to fix these yourself.
4555              
4556             =head1 THE DATETIME PROJECT ECOSYSTEM
4557              
4558             This module is part of a larger ecosystem of modules in the DateTime family.
4559              
4560             =head2 L<DateTime::Set>
4561              
4562             The L<DateTime::Set> module represents sets (including recurrences) of
4563             datetimes. Many modules return sets or recurrences.
4564              
4565             =head2 Format Modules
4566              
4567             The various format modules exist to parse and format datetimes. For example,
4568             L<DateTime::Format::HTTP> parses dates according to the RFC 1123 format:
4569              
4570             my $datetime
4571             = DateTime::Format::HTTP->parse_datetime(
4572             'Thu Feb 3 17:03:55 GMT 1994');
4573              
4574             print DateTime::Format::HTTP->format_datetime($datetime);
4575              
4576             Most format modules are suitable for use as a C<formatter> with a DateTime
4577             object.
4578              
4579             All format modules start with
4580             L<DateTime::Format::|https://metacpan.org/search?q=datetime%3A%3Aformat>.
4581              
4582             =head2 Calendar Modules
4583              
4584             There are a number of modules on CPAN that implement non-Gregorian calendars,
4585             such as the Chinese, Mayan, and Julian calendars.
4586              
4587             All calendar modules start with
4588             L<DateTime::Calendar::|https://metacpan.org/search?q=datetime%3A%3Acalendar>.
4589              
4590             =head2 Event Modules
4591              
4592             There are a number of modules that calculate the dates for events, such as
4593             Easter, Sunrise, etc.
4594              
4595             All event modules start with
4596             L<DateTime::Event::|https://metacpan.org/search?q=datetime%3A%3Aevent>.
4597              
4598             =head2 Others
4599              
4600             There are many other modules that work with DateTime, including modules in the
4601             L<DateTimeX namespace|https://metacpan.org/search?q=datetimex> namespace, as
4602             well as others.
4603              
4604             See L<MetaCPAN|https://metacpan.org/search?q=datetime> for more modules.
4605              
4606             =head1 KNOWN BUGS
4607              
4608             The tests in F<20infinite.t> seem to fail on some machines, particularly on
4609             Win32. This appears to be related to Perl's internal handling of IEEE infinity
4610             and NaN, and seems to be highly platform/compiler/phase of moon dependent.
4611              
4612             If you don't plan to use infinite datetimes you can probably ignore this. This
4613             will be fixed (perhaps) in future versions.
4614              
4615             =head1 SEE ALSO
4616              
4617             L<A Date with Perl|http://presentations.houseabsolute.com/a-date-with-perl/> -
4618             a talk I've given at a few YAPCs.
4619              
4620             L<datetime@perl.org mailing list|http://lists.perl.org/list/datetime.html>
4621              
4622             =head1 SUPPORT
4623              
4624             Bugs may be submitted at L<https://github.com/houseabsolute/DateTime.pm/issues>.
4625              
4626             There is a mailing list available for users of this distribution,
4627             L<mailto:datetime@perl.org>.
4628              
4629             =head1 SOURCE
4630              
4631             The source code repository for DateTime can be found at L<https://github.com/houseabsolute/DateTime.pm>.
4632              
4633             =head1 DONATIONS
4634              
4635             If you'd like to thank me for the work I've done on this module, please
4636             consider making a "donation" to me via PayPal. I spend a lot of free time
4637             creating free software, and would appreciate any support you'd care to offer.
4638              
4639             Please note that B<I am not suggesting that you must do this> in order for me
4640             to continue working on this particular software. I will continue to do so,
4641             inasmuch as I have in the past, for as long as it interests me.
4642              
4643             Similarly, a donation made in this way will probably not make me work on this
4644             software much more, unless I get so many donations that I can consider working
4645             on free software full time (let's all have a chuckle at that together).
4646              
4647             To donate, log into PayPal and send money to autarch@urth.org, or use the
4648             button at L<https://houseabsolute.com/foss-donations/>.
4649              
4650             =head1 AUTHOR
4651              
4652             Dave Rolsky <autarch@urth.org>
4653              
4654             =head1 CONTRIBUTORS
4655              
4656             =for stopwords Ben Bennett Christian Hansen Daisuke Maki Dan Book Stewart David Dyck E. Wheeler Precious Doug Bell Flávio Soibelmann Glock Gianni Ceccarelli Gregory Oschwald Hauke D Iain Truskett James Raspass Jason McIntosh Joshua Hoblitt Karen Etheridge Mark Overmeer Michael Conrad R. Davis Mohammad S Anwar M Somerville Nick Tonkin Olaf Alders Ovid Paul Howarth Philippe Bruhat (BooK) philip r brenan Ricardo Signes Richard Bowen Ron Hill Sam Kington viviparous
4657              
4658             =over 4
4659              
4660             =item *
4661              
4662             Ben Bennett <fiji@limey.net>
4663              
4664             =item *
4665              
4666             Christian Hansen <chansen@cpan.org>
4667              
4668             =item *
4669              
4670             Daisuke Maki <dmaki@cpan.org>
4671              
4672             =item *
4673              
4674             Dan Book <grinnz@gmail.com>
4675              
4676             =item *
4677              
4678             Dan Stewart <danielandrewstewart@gmail.com>
4679              
4680             =item *
4681              
4682             David Dyck <david.dyck@checksum.com>
4683              
4684             =item *
4685              
4686             David E. Wheeler <david@justatheory.com>
4687              
4688             =item *
4689              
4690             David Precious <davidp@preshweb.co.uk>
4691              
4692             =item *
4693              
4694             Doug Bell <madcityzen@gmail.com>
4695              
4696             =item *
4697              
4698             Flávio Soibelmann Glock <fglock@gmail.com>
4699              
4700             =item *
4701              
4702             Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
4703              
4704             =item *
4705              
4706             Gregory Oschwald <oschwald@gmail.com>
4707              
4708             =item *
4709              
4710             Hauke D <haukex@zero-g.net>
4711              
4712             =item *
4713              
4714             Iain Truskett <deceased>
4715              
4716             =item *
4717              
4718             James Raspass <jraspass@gmail.com>
4719              
4720             =item *
4721              
4722             Jason McIntosh <jmac@jmac.org>
4723              
4724             =item *
4725              
4726             Joshua Hoblitt <jhoblitt@cpan.org>
4727              
4728             =item *
4729              
4730             Karen Etheridge <ether@cpan.org>
4731              
4732             =item *
4733              
4734             Mark Overmeer <mark@overmeer.net>
4735              
4736             =item *
4737              
4738             Michael Conrad <mike@nrdvana.net>
4739              
4740             =item *
4741              
4742             Michael R. Davis <mrdvt92@users.noreply.github.com>
4743              
4744             =item *
4745              
4746             Mohammad S Anwar <mohammad.anwar@yahoo.com>
4747              
4748             =item *
4749              
4750             M Somerville <dracos@users.noreply.github.com>
4751              
4752             =item *
4753              
4754             Nick Tonkin <1nickt@users.noreply.github.com>
4755              
4756             =item *
4757              
4758             Olaf Alders <olaf@wundersolutions.com>
4759              
4760             =item *
4761              
4762             Ovid <curtis_ovid_poe@yahoo.com>
4763              
4764             =item *
4765              
4766             Paul Howarth <paul@city-fan.org>
4767              
4768             =item *
4769              
4770             Philippe Bruhat (BooK) <book@cpan.org>
4771              
4772             =item *
4773              
4774             philip r brenan <philiprbrenan@gmail.com>
4775              
4776             =item *
4777              
4778             Ricardo Signes <rjbs@cpan.org>
4779              
4780             =item *
4781              
4782             Richard Bowen <bowen@cpan.org>
4783              
4784             =item *
4785              
4786             Ron Hill <rkhill@cpan.org>
4787              
4788             =item *
4789              
4790             Sam Kington <github@illuminated.co.uk>
4791              
4792             =item *
4793              
4794             viviparous <viviparous@prc>
4795              
4796             =back
4797              
4798             =head1 COPYRIGHT AND LICENSE
4799              
4800             This software is Copyright (c) 2003 - 2023 by Dave Rolsky.
4801              
4802             This is free software, licensed under:
4803              
4804             The Artistic License 2.0 (GPL Compatible)
4805              
4806             The full text of the license can be found in the
4807             F<LICENSE> file included with this distribution.
4808              
4809             =cut