Profile of DateTime.pm

Filename	/usr/lib/x86_64-linux-gnu/perl5/5.20/DateTime.pm
Statements	Executed 0 statements in 0s

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