← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:44 2010

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