← Index
NYTProf Performance Profile   « block view • line view • sub view »
For -e
  Run on Sun Aug 5 15:24:32 2012
Reported on Sun Aug 5 15:24:50 2012

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