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