1NAME
2 Time::Moment - Represents a date and time of day with an offset from UTC
3
4SYNOPSIS
5 $tm = Time::Moment->new(
6 year => 2012,
7 month => 12,
8 day => 24,
9 hour => 15,
10 minute => 30,
11 second => 45,
12 nanosecond => 123456789,
13 offset => 0,
14 );
15 $tm = Time::Moment->now;
16 $tm = Time::Moment->now_utc;
17 $tm = Time::Moment->from_epoch($seconds);
18 $tm = Time::Moment->from_object($object);
19 $tm = Time::Moment->from_string($string);
20 $tm = Time::Moment->from_rd($rd);
21 $tm = Time::Moment->from_jd($jd);
22 $tm = Time::Moment->from_mjd($mjd);
23
24 $year = $tm->year; # [1, 9999]
25 $quarter = $tm->quarter; # [1, 4]
26 $month = $tm->month; # [1, 12]
27 $week = $tm->week; # [1, 53]
28
29 $day = $tm->day_of_year; # [1, 366]
30 $day = $tm->day_of_quarter; # [1, 92]
31 $day = $tm->day_of_month; # [1, 31]
32 $day = $tm->day_of_week; # [1=Monday, 7=Sunday]
33
34 $hour = $tm->hour; # [0, 23]
35 $minute = $tm->minute; # [0, 59]
36 $minute = $tm->minute_of_day; # [0, 1439]
37 $second = $tm->second; # [0, 59]
38 $second = $tm->second_of_day; # [0, 86_399]
39 $millisecond = $tm->millisecond; # [0, 999]
40 $millisecond = $tm->millisecond_of_day; # [0, 86_399_999]
41 $microsecond = $tm->microsecond; # [0, 999_999]
42 $microsecond = $tm->microsecond_of_day; # [0, 86_399_999_999]
43 $nanosecond = $tm->nanosecond; # [0, 999_999_999]
44 $nanosecond = $tm->nanosecond_of_day; # [0, 86_399_999_999_999]
45
46 $epoch = $tm->epoch;
47 $offset = $tm->offset; # [-1080, 1080] (±18:00)
48
49 $jd = $tm->jd; # Julian Date
50 $mjd = $tm->mjd; # Modified Julian Date
51 $rd = $tm->rd; # Rata Die
52
53 $tm2 = $tm1->with($adjuster);
54 $tm2 = $tm1->with_year($year);
55 $tm2 = $tm1->with_quarter($quarter);
56 $tm2 = $tm1->with_month($month);
57 $tm2 = $tm1->with_week($week);
58 $tm2 = $tm1->with_day_of_year($day);
59 $tm2 = $tm1->with_day_of_quarter($day);
60 $tm2 = $tm1->with_day_of_month($day);
61 $tm2 = $tm1->with_day_of_week($day);
62 $tm2 = $tm1->with_hour($hour);
63 $tm2 = $tm1->with_minute($minute);
64 $tm2 = $tm1->with_minute_of_day($minute);
65 $tm2 = $tm1->with_second($second);
66 $tm2 = $tm1->with_second_of_day($second);
67 $tm2 = $tm1->with_millisecond($millisecond);
68 $tm2 = $tm1->with_millisecond_of_day($millisecond);
69 $tm2 = $tm1->with_microsecond($microsecond);
70 $tm2 = $tm1->with_microsecond_of_day($microsecond);
71 $tm2 = $tm1->with_nanosecond($nanosecond);
72 $tm2 = $tm1->with_nanosecond_of_day($nanosecond);
73
74 $tm2 = $tm1->with_offset_same_instant($offset);
75 $tm2 = $tm1->with_offset_same_local($offset);
76
77 $tm2 = $tm1->with_precision($precision);
78
79 $tm2 = $tm1->plus_years($years);
80 $tm2 = $tm1->plus_months($months);
81 $tm2 = $tm1->plus_weeks($weeks);
82 $tm2 = $tm1->plus_days($days);
83 $tm2 = $tm1->plus_hours($hours);
84 $tm2 = $tm1->plus_minutes($minutes);
85 $tm2 = $tm1->plus_seconds($seconds);
86 $tm2 = $tm1->plus_milliseconds($milliseconds);
87 $tm2 = $tm1->plus_microseconds($microseconds);
88 $tm2 = $tm1->plus_nanoseconds($nanoseconds);
89
90 $tm2 = $tm1->minus_years($years);
91 $tm2 = $tm1->minus_months($months);
92 $tm2 = $tm1->minus_weeks($weeks);
93 $tm2 = $tm1->minus_days($days);
94 $tm2 = $tm1->minus_hours($hours);
95 $tm2 = $tm1->minus_minutes($minutes);
96 $tm2 = $tm1->minus_seconds($seconds);
97 $tm2 = $tm1->minus_milliseconds($milliseconds);
98 $tm2 = $tm1->minus_microseconds($microseconds);
99 $tm2 = $tm1->minus_nanoseconds($nanoseconds);
100
101 $years = $tm1->delta_years($tm2);
102 $months = $tm1->delta_months($tm2);
103 $weeks = $tm1->delta_weeks($tm2);
104 $days = $tm1->delta_days($tm2);
105 $hours = $tm1->delta_hours($tm2);
106 $minutes = $tm1->delta_minutes($tm2);
107 $seconds = $tm1->delta_seconds($tm2);
108 $milliseconds = $tm1->delta_milliseconds($tm2);
109 $microseconds = $tm1->delta_microseconds($tm2);
110 $nanoseconds = $tm1->delta_nanoseconds($tm2);
111
112 $tm2 = $tm1->at_utc;
113
114 $tm2 = $tm1->at_midnight; # T00:00:00.0
115 $tm2 = $tm1->at_noon; # T12:00:00.0
116
117 $tm2 = $tm1->at_last_day_of_year;
118 $tm2 = $tm1->at_last_day_of_quarter;
119 $tm2 = $tm1->at_last_day_of_month;
120
121 $boolean = $tm1->is_before($tm2);
122 $boolean = $tm1->is_after($tm2);
123 $boolean = $tm1->is_equal($tm2);
124
125 $integer = $tm1->compare($tm2);
126
127 $boolean = $tm->is_leap_year;
128
129 $string = $tm->to_string;
130 $string = $tm->strftime($format);
131
132 $integer = $tm->length_of_year; # [365, 366]
133 $integer = $tm->length_of_quarter; # [90, 92]
134 $integer = $tm->length_of_month; # [28, 31]
135 $integer = $tm->length_of_week_year; # [52, 53]
136
137 @values = $tm->utc_rd_values;
138 $seconds = $tm->utc_rd_as_seconds;
139 @values = $tm->local_rd_values;
140 $seconds = $tm->local_rd_as_seconds;
141
142 $integer = $tm1 <=> $tm2;
143
144 $boolean = $tm1 == $tm2;
145 $boolean = $tm1 != $tm2;
146 $boolean = $tm1 < $tm2;
147 $boolean = $tm1 > $tm2;
148 $boolean = $tm1 <= $tm2;
149 $boolean = $tm1 >= $tm2;
150
151 $string = "$tm";
152
153DESCRIPTION
154 "Time::Moment" is an immutable object representing a date and time of
155 day with an offset from UTC in the ISO 8601 calendar system.
156
157 Time is measured in nanoseconds since "0001-01-01T00Z". In "Time:Moment"
158 leap seconds are ignored. It is assumed that there are exactly
159 "86,400,000,000,000" nanoseconds per day. "Time::Moment" can represent
160 all epoch integers from "-62,135,596,800" to "253,402,300,799"; this
161 range suffices to measure times to nanosecond precision for any instant
162 that is within "0001-01-01T00:00:00Z" to "9999-12-31T23:59:59Z".
163
164CONSTRUCTORS
165 new
166 $tm = Time::Moment->new(
167 year => 2012,
168 month => 12,
169 day => 24,
170 hour => 15,
171 minute => 30,
172 second => 45,
173 nanosecond => 123456789,
174 offset => 0,
175 );
176
177 Constructs an instance of "Time::Moment" from the given components.
178
179 Parameters:
180
181 year
182 The year [1, 9999].
183
184 month
185 The month of the year [1, 12].
186
187 day The day of the month [1, 31]. The day must be valid for the year and
188 month, otherwise an exception is raised.
189
190 hour
191 The hour of the day [0, 23].
192
193 minute
194 The minute of the hour [0, 59].
195
196 second
197 The second of the minute [0, 59].
198
199 nanosecond
200 The nanosecond of the second [0, 999_999_999].
201
202 offset
203 The offset from UTC in minutes [-1080, 1080] (±18:00).
204
205 now
206 $tm = Time::Moment->now;
207
208 Constructs an instance of "Time::Moment" that is set to the current date
209 and time from the system clock in the system time zone, with the offset
210 set to the system's time zone offset from UTC.
211
212 now_utc
213 $tm = Time::Moment->now_utc;
214
215 Constructs an instance of "Time::Moment" that is set to the current date
216 and time from the system clock in the UTC time zone.
217
218 from_epoch
219 $tm = Time::Moment->from_epoch($seconds);
220 $tm = Time::Moment->from_epoch($seconds, $nanosecond);
221 $tm = Time::Moment->from_epoch($seconds [, nanosecond => 0] [, precision => 6]);
222
223 Constructs an instance of "Time::Moment" from the given *seconds* from
224 the epoch of 1970-01-01T00Z. Fractional seconds is supported if the
225 constructor is invoked with *seconds* only, the default precision is 6
226 (microseconds).
227
228 Parameters:
229
230 nanosecond
231 $tm = Time::Moment->from_epoch($seconds, nanosecond => 0);
232
233 The optional parameter *nanosecond* [0, 999_999_999] specifies the
234 nanosecond of the second.
235
236 precision
237 $tm = Time::Moment->from_epoch($seconds, precision => 6);
238
239 The optional parameter *precision* [0, 9] specifies the precision of
240 the fractional seconds. The default precision is 6 (microseconds).
241
242 from_object
243 $tm = Time::Moment->from_object($object);
244
245 Constructs an instance of "Time::Moment" from the given *object*. If the
246 given object is an instance of "Time::Moment" it's returned otherwise an
247 attempt is made to coerce the given object to an instance of
248 "Time::Moment".
249
250 "Time::Moment" implements coercion handlers for the following object
251 types:
252
253 DateTime
254 $tm = Time::Moment->from_object( DateTime->now );
255
256 The given "DateTime" object must be within the supported range and
257 must have a time zone or an offset from UTC, coercing from the
258 'floating' time zone is not supported.
259
260 Time::Piece
261 $tm = Time::Moment->from_object( scalar Time::Piece::localtime() );
262
263 The given "Time::Piece" object must be within the supported date
264 range.
265
266 The coercion scheme is extensible and implemented as documented in
267 Params::Coerce:
268
269 $tm = Params::Coerce::coerce('Time::Moment', scalar Time::Piece::localtime());
270 $tm = Params::Coerce::coerce('Time::Moment', DateTime->now);
271
272 "Time::Moment" also implements a coercion handler from "Time::Moment" to
273 "DateTime" and "Time::Piece":
274
275 $dt = Params::Coerce::coerce('DateTime', Time::Moment->now);
276 $tp = Params::Coerce::coerce('Time::Piece', Time::Moment->now);
277
278 from_string
279 $tm = Time::Moment->from_string($string);
280 $tm = Time::Moment->from_string($string [, lenient => false]);
281
282 Constructs an instance of "Time::Moment" from the given *string*. The
283 string must consist of a complete date representation and time of day
284 followed by a zone designator. The time of day may be reduced to hour of
285 the day, the second of the minute may have a decimal fraction. The
286 decimal sign can be either the comma [,] or the full stop [.]. A decimal
287 fraction must have at least one digit and may have a total of nine
288 digits, if the fractional precision is greater than nine digits, the
289 value will be truncated.
290
291 The following are examples of complete date and time of day
292 representations:
293
294 Basic format: Example:
295 YYYYMMDDThhmmssZ 20121224T121530Z
296 YYYYMMDDThhmmss±hhmm 20121224T121530+0100
297 YYYYMMDDThhmmss±hh 20121224T121530+01
298
299 YYYYMMDDThhmmss.ssZ 20121224T121530.500Z
300 YYYYMMDDThhmmss.ss±hhmm 20121224T121530.500+0100
301 YYYYMMDDThhmmss.ss±hh 20121224T121530.500+01
302
303 YYYYMMDDThhZ 20121224T12Z (reduced accuracy)
304 YYYYMMDDThhmmZ 20121224T1215Z (reduced accuracy)
305 YYYYMMDDThhmm±hhmm 20121224T1215+0100 (reduced accuracy)
306 YYYYMMDDThhmm±hh 20121224T1215+01 (reduced accuracy)
307
308 Extended format: Example:
309 YYYY-MM-DDThh:mm:ssZ 2012-12-24T12:15:30Z
310 YYYY-MM-DDThh:mm:ss±hh:mm 2012-12-24T12:15:30+01:00
311 YYYY-MM-DDThh:mm:ss±hh 2012-12-24T12:15:30+01
312
313 YYYY-MM-DDThh:mm:ss.ssZ 2012-12-24T12:15:30.500Z
314 YYYY-MM-DDThh:mm:ss.ss±hh:mm 2012-12-24T12:15:30.500+01:00
315 YYYY-MM-DDThh:mm:ss.ss±hh 2012-12-24T12:15:30.500+01
316
317 YYYY-MM-DDThhZ 2012-12-24T12Z (reduced accuracy)
318 YYYY-MM-DDThh:mmZ 2012-12-24T12:15Z (reduced accuracy)
319 YYYY-MM-DDThh:mm±hh:mm 2012-12-24T12:15+01:00 (reduced accuracy)
320 YYYY-MM-DDThh:mm±hh 2012-12-24T12:15+01 (reduced accuracy)
321
322 Where representations using calendar dates are shown, ordinal dates or
323 week dates may be substituted. This ISO 8601 profile correspond to a
324 subset of ISO 8601:2004 4.3 Date and time of day.
325
326 If the optional boolean parameter *lenient* is true, the following
327 examples are also accepted:
328
329 YYYY-MM-DD hh:mm:ssZ 2012-12-24 12:15:30Z
330 YYYY-MM-DD hh:mm:ssz 2012-12-24 12:15:30z
331 YYYY-MM-DD hh:mm:ss±hhmm 2012-12-24 12:15:30+0100
332 YYYY-MM-DD hh:mm:ss±hh:mm 2012-12-24 12:15:30+01:00
333 YYYY-MM-DD hh:mm:ss±hh 2012-12-24 12:15:30+01
334
335 YYYY-MM-DD hh:mm:ss.ssZ 2012-12-24 12:15:30.500Z
336 YYYY-MM-DD hh:mm:ss.ssz 2012-12-24 12:15:30.500z
337 YYYY-MM-DD hh:mm:ss.ss±hhmm 2012-12-24 12:15:30.500+0100
338 YYYY-MM-DD hh:mm:ss.ss±hh:mm 2012-12-24 12:15:30.500+01:00
339 YYYY-MM-DD hh:mm:ss.ss±hh 2012-12-24 12:15:30.500+01
340
341 YYYY-MM-DD hh:mmZ 2012-12-24 12:15Z
342 YYYY-MM-DD hh:mmz 2012-12-24 12:15z
343 YYYY-MM-DD hh:mm±hhmm 2012-12-24 12:15+0100
344 YYYY-MM-DD hh:mm±hh:mm 2012-12-24 12:15+01:00
345 YYYY-MM-DD hh:mm±hh 2012-12-24 12:15+01
346
347 YYYY-MM-DD hh:mm:ss ±hh:mm 2012-12-24 12:15:30 +01:00
348 YYYY-MM-DD hh:mm:ss ±hhmm 2012-12-24 12:15:30 +0100
349 YYYY-MM-DD hh:mm:ss ±hh 2012-12-24 12:15:30 +01
350 YYYY-MM-DD hh:mm:ss GMT 2012-12-24 12:15:30 GMT
351 YYYY-MM-DD hh:mm:ss GMT±hh 2012-12-24 12:15:30 GMT+01
352 YYYY-MM-DD hh:mm:ss UTC 2012-12-24 12:15:30 UTC
353 YYYY-MM-DD hh:mm:ss UTC±hh 2012-12-24 12:15:30 UTC+01
354
355 YYYY-MM-DD hh:mm:ss.ss ±hhmm 2012-12-24 12:15:30.500 +0100
356 YYYY-MM-DD hh:mm:ss.ss ±hh:mm 2012-12-24 12:15:30.500 +01:00
357 YYYY-MM-DD hh:mm:ss.ss ±hh 2012-12-24 12:15:30.500 +01
358
359 YYYY-MM-DD hh:mm ±hh:mm 2012-12-24 12:15 +01:00
360 YYYY-MM-DD hh:mm ±hhmm 2012-12-24 12:15 +0100
361 YYYY-MM-DD hh:mm ±hh 2012-12-24 12:15 +01
362
363 The string representation may consist of a mixture of the basic format
364 and the extended format. The time designator [T] may be in lower case
365 [t] or replaced with a single space. A single space is also accepted
366 between the time of day and the zone designator. The UTC designator [Z]
367 may also be in lower case [z]. The literal string GMT or UTC may be used
368 as a UTC designator and may have an offset. Usage of these string
369 representations is strongly discouraged as they do not conform to the
370 ISO 8601 standard.
371
372 from_rd
373 $tm = Time::Moment->from_rd($rd);
374 $tm = Time::Moment->from_rd($rd [, offset => 0] [, precision => 3] [, epoch => 0]);
375
376 Constructs an instance of "Time::Moment" from the given Rata Die. The
377 Rata Die is a count of days elapsed since 0000-12-31T00. The fractional
378 part corresponds to the fraction of the day after midnight. The minimum
379 acceptable Rata Die is 1 which corresponds to 0001-01-01T00.
380
381 Parameters:
382
383 offset
384 $tm = Time::Moment->from_rd($rd, offset => 0);
385
386 The optional parameter *offset* [-1080, 1080] (±18:00) specifies the
387 offset from UTC in minutes. The default offset is 0.
388
389 precision
390 $tm = Time::Moment->from_rd($rd, precision => 3);
391
392 The optional parameter *precision* [0, 9] specifies the precision of
393 the fractional seconds. The default precision is 3 (milliseconds).
394
395 epoch
396 $tm = Time::Moment->from_rd($rd, epoch => 0);
397
398 The optional parameter *epoch* specifies the epoch date relative to
399 0000-12-31T00. The epoch date for the Rata Die is 0.
400
401 from_jd
402 $tm = Time::Moment->from_jd($jd);
403 $tm = Time::Moment->from_jd($jd [, precision => 3] [, epoch => -1721424.5]);
404
405 Constructs an instance of "Time::Moment" from the given Julian Date. The
406 Julian Date is a count of days elapsed since -4713-11-24T12Z. The
407 fractional part corresponds to the fraction of the day after noon. The
408 minimum acceptable Julian Date is 1721425.5 which corresponds to
409 0001-01-01T00Z.
410
411 Parameters:
412
413 precision
414 $tm = Time::Moment->from_jd($jd, precision => 3);
415
416 The optional parameter *precision* [0, 9] specifies the precision of
417 the fractional seconds. The default precision is 3 (milliseconds).
418
419 epoch
420 $tm = Time::Moment->from_jd($jd, epoch => -1721424.5);
421
422 The optional parameter *epoch* specifies the epoch date relative to
423 0000-12-31T00Z. The epoch date for the Julian Date is -1721424.5.
424
425 from_mjd
426 $tm = Time::Moment->from_mjd($mjd);
427 $tm = Time::Moment->from_mjd($mjd [, precision => 3] [, epoch => 678576]);
428
429 Constructs an instance of "Time::Moment" from the given Modified Julian
430 Date. The Modified Julian Date is a count of days elapsed since
431 1858-11-17T00Z. The fractional part corresponds to the fraction of the
432 day after midnight. The minimum acceptable Modified Julian Date is
433 -678575 which corresponds to 0001-01-01T00Z.
434
435 Parameters:
436
437 precision
438 $tm = Time::Moment->from_mjd($mjd, precision => 3);
439
440 The optional parameter *precision* [0, 9] specifies the precision of
441 the fractional seconds. The default precision is 3 (milliseconds).
442
443 epoch
444 $tm = Time::Moment->from_mjd($mjd, epoch => 678576);
445
446 The optional parameter *epoch* specifies the epoch date relative to
447 0000-12-31T00Z. The epoch date for the Modified Julian Date is
448 678576.
449
450INSTANCE METHODS
451 year
452 $year = $tm->year;
453
454 Returns the year [1, 9999].
455
456 quarter
457 $quarter = $tm->quarter;
458
459 Returns the quarter of the year [1, 4].
460
461 month
462 $month = $tm->month;
463
464 Returns the month of the year [1, 12].
465
466 week
467 $week = $tm->week;
468
469 Returns the week of the year [1, 53].
470
471 day_of_year
472 $day = $tm->day_of_year;
473
474 Returns the day of the year [1, 366].
475
476 day_of_quarter
477 $day = $tm->day_of_quarter;
478
479 Returns the day of the quarter [1, 92].
480
481 day_of_month
482 $day = $tm->day_of_month;
483
484 Returns the day of the month [1, 31].
485
486 day_of_week
487 $day = $tm->day_of_week;
488
489 Returns the day of the week [1=Monday, 7=Sunday].
490
491 hour
492 $hour = $tm->hour;
493
494 Returns the hour of the day [0, 23].
495
496 minute
497 $minute = $tm->minute;
498
499 Returns the minute of the hour [0, 59].
500
501 minute_of_day
502 $minute = $tm->minute_of_day;
503
504 Returns the minute of the day [0, 1439].
505
506 second
507 $second = $tm->second;
508
509 Returns the second of the minute [0, 59].
510
511 second_of_day
512 $second = $tm->second_of_day;
513
514 Returns the second of the day [0, 86_399].
515
516 millisecond
517 $millisecond = $tm->millisecond;
518
519 Returns the millisecond of the second [0, 999].
520
521 millisecond_of_day
522 $millisecond = $tm->millisecond_of_day;
523
524 Returns the millisecond of the day [0, 86_399_999].
525
526 microsecond
527 $microsecond = $tm->microsecond;
528
529 Returns the microsecond of the second [0, 999_999].
530
531 microsecond_of_day
532 $microsecond = $tm->microsecond_of_day;
533
534 Returns the microsecond of the day [0, 86_399_999_999].
535
536 nanosecond
537 $nanosecond = $tm->nanosecond;
538
539 Returns the nanosecond of the second [0, 999_999_999].
540
541 nanosecond_of_day
542 $nanosecond = $tm->nanosecond_of_day;
543
544 Returns the nanosecond of the day [0, 86_399_999_999_999].
545
546 epoch
547 $epoch = $tm->epoch;
548
549 Returns the number of integral seconds from the epoch of 1970-01-01T00Z.
550
551 offset
552 $offset = $tm->offset;
553
554 Returns the offset from UTC in minutes [-1080, 1080] (±18:00).
555
556 precision
557 $precision = $tm->precision;
558
559 Returns the precision of the time of the day [-3, 9]. Please see
560 with_precision for an explanation of the returned precision value.
561
562 jd
563 $jd = $tm->jd;
564 $jd = $tm->jd([precision => 3]);
565
566 Returns the Julian Date. The Julian Date is a count of days elapsed
567 since -4713-11-24T12Z. The fractional part corresponds to the fraction
568 of the day after noon. The optional named parameter *precision* [0, 9]
569 specifies the precision of the fractional seconds. The default precision
570 is 3 (milliseconds).
571
572 mjd
573 $mjd = $tm->mjd;
574 $mjd = $tm->mjd([precision => 3]);
575
576 Returns the Modified Julian Date. The Modified Julian Date is a count of
577 days elapsed since 1858-11-17T00Z. The fractional part corresponds to
578 the fraction of the day after midnight. The optional named parameter
579 *precision* [0, 9] specifies the precision of the fractional seconds.
580 The default precision is 3 (milliseconds).
581
582 rd
583 $rd = $tm->rd;
584 $rd = $tm->rd([precision => 3]);
585
586 Returns the Rata Die. The Rata Die is a count of days elapsed since
587 0000-12-31T00. The fractional part corresponds to the fraction of the
588 day after midnight. The optional named parameter *precision* [0, 9]
589 specifies the precision of the fractional seconds. The default precision
590 is 3 (milliseconds).
591
592 with
593 $tm2 = $tm1->with($adjuster);
594
595 Returns a copy of this instance adjusted by the given *adjuster*. The
596 adjuster is a CODE reference invoked with an instance of Time::Moment
597 and is expected to return an instance of Time::Moment. Please see
598 Time::Moment::Adjusters for available adjusters.
599
600 with_year
601 $tm2 = $tm1->with_year($year);
602
603 Returns a copy of this instance with the given *year* [1, 9999] altered.
604 The day of the month of the date is unchanged unless the day does not
605 exist in the month. In that case, the day is set to the last day of the
606 month.
607
608 with_quarter
609 $tm2 = $tm1->with_quarter($quarter);
610
611 Returns a copy of this instance with the given *quarter* of the year [1,
612 4] altered. The day of the month of the date is unchanged unless the day
613 does not exist in the month of the quarter. In that case, the day is set
614 to the last day of the month.
615
616 with_month
617 $tm2 = $tm1->with_month($month);
618
619 Returns a copy of this instance with the given *month* of the year [1,
620 12] altered. The day of the month of the date is unchanged unless the
621 day does not exist in the given month. In that case, the day is set to
622 the last day of the given month.
623
624 with_week
625 $tm2 = $tm1->with_week($week);
626
627 Returns a copy of this instance with the given *week* of the year [1,
628 53] altered. The week must be valid for the year, otherwise an exception
629 is raised.
630
631 with_day_of_year
632 $tm2 = $tm1->with_day_of_year($day);
633
634 Returns a copy of this instance with the given *day* of the year [1,
635 366] altered. The day must be valid for the year, otherwise an exception
636 is raised.
637
638 with_day_of_quarter
639 $tm2 = $tm1->with_day_of_quarter($day);
640
641 Returns a copy of this instance with the given *day* of the quarter [1,
642 92] altered. The day must be valid for the year and quarter, otherwise
643 an exception is raised.
644
645 with_day_of_month
646 $tm2 = $tm1->with_day_of_month($day);
647
648 Returns a copy of this instance with the given *day* of the month [1,
649 31] altered. The day must be valid for the year and month, otherwise an
650 exception is raised.
651
652 with_day_of_week
653 $tm2 = $tm1->with_day_of_week($day);
654
655 Returns a copy of this instance with the given *day* of the week
656 [1=Monday, 7=Sunday] altered.
657
658 with_hour
659 $tm2 = $tm1->with_hour($hour);
660
661 Returns a copy of this instance with the given *hour* of the day [0, 23]
662 altered.
663
664 with_minute
665 $tm2 = $tm1->with_minute($minute);
666
667 Returns a copy of this instance with the given *minute* of the hour [0,
668 59] altered.
669
670 with_minute_of_day
671 $tm2 = $tm1->with_minute_of_day($minute);
672
673 Returns a copy of this instance with the given *minute* of the day [0,
674 1439] altered, any lower-order time elements is unaltered.
675
676 with_second
677 $tm2 = $tm1->with_second($second);
678
679 Returns a copy of this instance with the given *second* of the minute
680 [0, 59] altered.
681
682 with_second_of_day
683 $tm2 = $tm1->with_second_of_day($second);
684
685 Returns a copy of this instance with the given *second* of the day [0,
686 86_399] altered, any lower-order time elements is unaltered.
687
688 with_millisecond
689 $tm2 = $tm1->with_millisecond($millisecond);
690
691 Returns a copy of this instance with the given *millisecond* of the
692 second [0, 999] altered. The nanosecond of the second is replaced with
693 the given *millisecond* multiplied by 1,000,000.
694
695 with_millisecond_of_day
696 $tm2 = $tm1->with_millisecond_of_day($millisecond);
697
698 Returns a copy of this instance with the given *millisecond* of the day
699 [0, 86_400_000] altered. A millisecond value of 86_400_000 (T24:00) is
700 normalized to midnight of the following day, any lower-order time
701 elements is truncated.
702
703 with_microsecond
704 $tm2 = $tm1->with_microsecond($microsecond);
705
706 Returns a copy of this instance with the given *microsecond* of the
707 second [0, 999_999] altered. The nanosecond of the second is replaced
708 with the given *microsecond* multiplied by 1,000.
709
710 with_microsecond_of_day
711 $tm2 = $tm1->with_microsecond_of_day($microsecond);
712
713 Returns a copy of this instance with the given *microsecond* of the day
714 [0, 86_400_000_000] altered. A microsecond value of 86_400_000_000
715 (T24:00) is normalized to midnight of the following day, any lower-order
716 time elements is truncated.
717
718 with_nanosecond
719 $tm2 = $tm1->with_nanosecond($nanosecond);
720
721 Returns a copy of this instance with the given *nanosecond* of the
722 second [0, 999_999_999] altered.
723
724 with_nanosecond_of_day
725 $tm2 = $tm1->with_nanosecond_of_day($nanosecond);
726
727 Returns a copy of this instance with the given *nanosecond* of the day
728 [0, 86_400_000_000_000] altered. A nanosecond value of
729 86_400_000_000_000 (T24:00) is normalized to midnight of the following
730 day.
731
732 with_offset_same_instant
733 $tm2 = $tm1->with_offset_same_instant($offset);
734
735 Returns a copy of this instance with the given *offset* from UTC in
736 minutes [-1080, 1080] (±18:00) altered. The resulting time is at the
737 same instant.
738
739 $tm = Time::Moment->from_string('2012-12-24T15-05')
740 ->with_offset_same_instant(0);
741 say $tm; # 2012-12-24T20Z
742
743 with_offset_same_local
744 $tm2 = $tm1->with_offset_same_local($offset);
745
746 Returns a copy of this instance with the given *offset* from UTC in
747 minutes [-1080, 1080] (±18:00) altered. The resulting time has the same
748 local time.
749
750 $tm = Time::Moment->from_string('2012-12-24T15-05')
751 ->with_offset_same_local(0);
752 say $tm; # 2012-12-24T15Z
753
754 with_precision
755 $tm2 = $tm1->with_precision($precision);
756
757 Returns a copy of this instance with the time of the day altered to the
758 given *precision* [-3, 9]. A precision value between [0, 9] alters the
759 precision of the fractional seconds. A precision of -1 truncates to
760 minute of the hour; -2 truncates to hour of the day; -3 truncates to
761 midnight of the day.
762
763 $tm = Time::Moment->from_string('2012-12-24T12:30:45.123456789Z');
764 say $tm->with_precision(6); # T12:30:45.123456Z
765 say $tm->with_precision(3); # T12:30:45.123Z
766 say $tm->with_precision(0); # T12:30:45Z
767 say $tm->with_precision(-1); # T12:30:00Z
768 say $tm->with_precision(-2); # T12:00:00Z
769 say $tm->with_precision(-3); # T00:00:00Z
770
771 plus_years
772 $tm2 = $tm1->plus_years($years);
773
774 Returns a copy of this instance with the given number of *years* added.
775 The day of the month of the date is unchanged unless the day does not
776 exist in the resulting month. In that case, the day is set to the last
777 day of the resulting month. For example, 2012-02-29 plus one year
778 results in 2013-02-28.
779
780 plus_months
781 $tm2 = $tm1->plus_months($months);
782
783 Returns a copy of this instance with the given number of *months* added.
784 The day of the month of the date is unchanged unless the day does not
785 exist in the resulting month. In that case, the day is set to the last
786 day of the resulting month. For example, 2013-01-31 plus one month
787 results in 2013-02-28; 2013-02-28 plus one month results in 2013-03-28.
788
789 plus_weeks
790 $tm2 = $tm1->plus_weeks($weeks);
791
792 Returns a copy of this instance with the given number of *weeks* added.
793
794 plus_days
795 $tm2 = $tm1->plus_days($days);
796
797 Returns a copy of this instance with the given number of *days* added.
798
799 plus_hours
800 $tm2 = $tm1->plus_hours($hours);
801
802 Returns a copy of this instance with the given number of *hours* added.
803
804 plus_minutes
805 $tm2 = $tm1->plus_minutes($minutes);
806
807 Returns a copy of this instance with the given number of *minutes*
808 added.
809
810 plus_seconds
811 $tm2 = $tm1->plus_seconds($seconds);
812
813 Returns a copy of this instance with the given number of *seconds*
814 added.
815
816 plus_milliseconds
817 $tm2 = $tm1->plus_milliseconds($milliseconds);
818
819 Returns a copy of this instance with the given number of *milliseconds*
820 added.
821
822 plus_microseconds
823 $tm2 = $tm1->plus_microseconds($microseconds);
824
825 Returns a copy of this instance with the given number of *microseconds*
826 added.
827
828 plus_nanoseconds
829 $tm2 = $tm1->plus_nanoseconds($nanoeconds);
830
831 Returns a copy of this instance with the given number of *nanoseconds*
832 added.
833
834 minus_years
835 $tm2 = $tm1->minus_years($years);
836
837 Returns a copy of this instance with the given number of *years*
838 subtracted. The day of the month of the date is unchanged unless the day
839 does not exist in the resulting month. In that case, the day is set to
840 the last day of the resulting month. For example, 2012-02-29 minus one
841 year results in 2011-02-28.
842
843 minus_months
844 $tm2 = $tm1->minus_months($months);
845
846 Returns a copy of this instance with the given number of *months*
847 subtracted. The day of the month of the date is unchanged unless the day
848 does not exist in the resulting month. In that case, the day is set to
849 the last day of the resulting month. For example, 2013-03-31 minus one
850 month results in 2013-02-28; 2013-02-28 minus one month results in
851 2013-01-28.
852
853 minus_weeks
854 $tm2 = $tm1->minus_weeks($weeks);
855
856 Returns a copy of this instance with the given number of *weeks*
857 subtracted.
858
859 minus_days
860 $tm2 = $tm1->minus_days($days);
861
862 Returns a copy of this instance with the given number of *days*
863 subtracted.
864
865 minus_hours
866 $tm2 = $tm1->minus_hours($hours);
867
868 Returns a copy of this instance with the given number of *hours*
869 subtracted.
870
871 minus_minutes
872 $tm2 = $tm1->minus_minutes($minutes);
873
874 Returns a copy of this instance with the given number of *minutes*
875 subtracted.
876
877 minus_seconds
878 $tm2 = $tm1->minus_seconds($seconds);
879
880 Returns a copy of this instance with the given number of *seconds*
881 subtracted.
882
883 minus_milliseconds
884 $tm2 = $tm1->minus_milliseconds($milliseconds);
885
886 Returns a copy of this instance with the given number of *milliseconds*
887 subtracted.
888
889 minus_microseconds
890 $tm2 = $tm1->minus_microseconds($microseconds);
891
892 Returns a copy of this instance with the given number of *microseconds*
893 subtracted.
894
895 minus_nanoseconds
896 $tm2 = $tm1->minus_nanoseconds($nanoseconds);
897
898 Returns a copy of this instance with the given number of *nanoseconds*
899 subtracted.
900
901 delta_years
902 $years = $tm->delta_years($other);
903
904 Returns the difference between the local date of this moment and the
905 *other* in terms of complete years. The result will be negative if the
906 local date of the *other* moment is before this.
907
908 delta_months
909 $months = $tm->delta_months($other);
910
911 Returns the difference between the local date of this moment and the
912 *other* in terms of complete months. The result will be negative if the
913 local date of the *other* moment is before this.
914
915 delta_weeks
916 $weeks = $tm->delta_weeks($other);
917
918 Returns the difference between the local date of this moment and the
919 *other* in terms of complete weeks. The result will be negative if the
920 local date of the *other* moment is before this.
921
922 delta_days
923 $days = $tm->delta_days($other);
924
925 Returns the difference between the local date of this moment and the
926 *other* in terms of complete days. The result will be negative if the
927 local date of the *other* moment is before this.
928
929 delta_hours
930 $hours = $tm->delta_hours($other);
931
932 Returns the difference between the instant of this moment and the
933 *other* in terms of complete hours. The result will be negative if the
934 instant of the *other* moment is before this.
935
936 delta_minutes
937 $minutes = $tm->delta_minutes($other);
938
939 Returns the difference between the instant of this moment and the
940 *other* in terms of complete minutes. The result will be negative if the
941 instant of the *other* moment is before this.
942
943 delta_seconds
944 $seconds = $tm->delta_seconds($other);
945
946 Returns the difference between the instant of this moment and the
947 *other* in terms of complete seconds. The result will be negative if the
948 instant of the *other* moment is before this.
949
950 delta_milliseconds
951 $milliseconds = $tm->delta_milliseconds($other);
952
953 Returns the difference between the instant of this moment and the
954 *other* in terms of complete milliseconds. The result will be negative
955 if the instant of the *other* moment is before this.
956
957 delta_microseconds
958 $microseconds = $tm->delta_microseconds($other);
959
960 Returns the difference between the instant of this moment and the
961 *other* in terms of complete microseconds. The result will be negative
962 if the instant of the *other* moment is before this.
963
964 delta_nanoseconds
965 $nanoseconds = $tm->delta_nanoseconds($other);
966
967 Returns the difference between the instant of this moment and the
968 *other* in terms of complete nanoseconds. The result will be negative if
969 the instant of the *other* moment is before this.
970
971 at_utc
972 $tm2 = $tm1->at_utc;
973
974 Returns a copy of this instance with the offset from UTC set to zero.
975 This method is equivalent to:
976
977 $tm2 = $tm1->with_offset_same_instant(0);
978
979 at_midnight
980 $tm2 = $tm1->at_midnight;
981
982 Returns a copy of this instance with the time of day set to midnight,
983 T00:00:00.0. This method is equivalent to:
984
985 $tm2 = $tm1->with_hour(0)
986 ->with_minute(0)
987 ->with_second(0)
988 ->with_nanosecond(0);
989
990 at_noon
991 $tm2 = $tm1->at_noon;
992
993 Returns a copy of this instance with the time of day set to noon,
994 T12:00:00.0. This method is equivalent to:
995
996 $tm2 = $tm1->with_hour(12)
997 ->with_minute(0)
998 ->with_second(0)
999 ->with_nanosecond(0);
1000
1001 at_last_day_of_year
1002 $tm2 = $tm1->at_last_day_of_year;
1003
1004 Returns a copy of this instance with the date adjusted to the last day
1005 of the year, the time of the day is unaltered.
1006
1007 at_last_day_of_quarter
1008 $tm2 = $tm1->at_last_day_of_quarter;
1009
1010 Returns a copy of this instance with the date adjusted to the last day
1011 of the quarter, the time of the day is unaltered.
1012
1013 at_last_day_of_month
1014 $tm2 = $tm1->at_last_day_of_month;
1015
1016 Returns a copy of this instance with the date adjusted to the last day
1017 of the month, the time of the day is unaltered.
1018
1019 is_before
1020 $boolean = $tm->is_before($other);
1021
1022 Returns a boolean indicating whether or not the instant of this time is
1023 before the *other* time.
1024
1025 is_after
1026 $boolean = $tm->is_after($other);
1027
1028 Returns a boolean indicating whether or not the instant of this time is
1029 after the *other* time.
1030
1031 is_equal
1032 $boolean = $tm->is_equal($other);
1033
1034 Returns a boolean indicating whether or not the instant of this time is
1035 equal the *other* time.
1036
1037 compare
1038 $integer = $tm->compare($other);
1039 $integer = $tm->compare($other [, precision => 9]);
1040
1041 Returns an integer indicating whether the instant of this time is
1042 before, after or equal the *other* time. Returns a value less than zero
1043 if this time is before the other; zero if this date is equal the other
1044 time; a value greater than zero if this time is after the other time.
1045 The optional parameter *precision* [-3, 9] specifies the precision of
1046 the comparison. The default precision is 9 (nanoseconds). Please see
1047 with_precision for an explanation of the precision value.
1048
1049 is_leap_year
1050 $boolean = $tm->is_leap_year;
1051
1052 Returns a boolean indicating whether or not the year of the local date
1053 of this moment is a leap year.
1054
1055 to_string
1056 $string = $tm->to_string;
1057 $string = $tm->to_string([reduced => false]);
1058
1059 Returns a string representation of the instance. If the optional named
1060 boolean parameter *reduced* is true a shorter representation is
1061 attempted.
1062
1063 The string will be in one of the following representations:
1064
1065 YYYY-MM-DDThh:mm (only if reduced => true)
1066 YYYY-MM-DDThh:mm:ss
1067 YYYY-MM-DDThh:mm:ss.fff
1068 YYYY-MM-DDThh:mm:ss.ffffff
1069 YYYY-MM-DDThh:mm:ss.fffffffff
1070
1071 Followed by a zone designator in one of the following representations:
1072
1073 Z
1074 ±hh (only if reduced => true)
1075 ±hh:mm
1076
1077 The shortest representation will be used where the omitted parts are
1078 implied to be zero.
1079
1080 strftime
1081 $string = $tm->strftime($format);
1082
1083 Formats time according to the conversion specifications in the given
1084 $format string. The format string consists of zero or more conversion
1085 specifications and ordinary characters. All ordinary characters are
1086 copied directly into the resulting string. A conversion specification
1087 consists of a percent sign "%" and one other character.
1088
1089 The following conversion specifications are supported:
1090
1091 %a Replaced by the C locale's abbreviated day of the week name.
1092 Example: Mon, Tue, ..., Sun.
1093
1094 %A Replaced by the C locale's full day of the week name. Example:
1095 Monday, Tuesday, ..., Sunday.
1096
1097 %b Replaced by the C locale's abbreviated month name. Example: Jan,
1098 Feb, ..., Dec.
1099
1100 %B Replaced by the C locale's full month name. Example: January,
1101 February, ..., December.
1102
1103 %c Replaced by the C locale's date and time representation. Equivalent
1104 to "%a %b %e %H:%M:%S %Y".
1105
1106 %C Replaced by the year divided by 100 and truncated to an integer, as
1107 a decimal number [00, 99].
1108
1109 %d Replaced by the day of the month as a decimal number [01, 31].
1110
1111 %D Equivalent to "%m/%d/%y".
1112
1113 %e Replaced by the day of the month as a decimal number [1, 31]; a
1114 single digit is preceded by a space.
1115
1116 %f Replaced by the fractional second including the preceding decimal
1117 point or by an empty string if no fractional seconds are present.
1118 This conversion specification permits use of an optional maximum
1119 field width [0, 9] where the default field width of 0 will use the
1120 shortest of the following representations:
1121
1122 .fff (millisecond)
1123 .ffffff (microsecond)
1124 .fffffffff (nanosecond)
1125
1126 Example:
1127
1128 $tm = Time::Moment->from_string('2012-12-24T15:30:45.123456Z');
1129 $tm->strftime('%f'); # '.123456'
1130 $tm->strftime('%3f'); # '.123'
1131 $tm->strftime('%9f'); # '.123456000'
1132
1133 $tm = Time::Moment->from_string('2012-12-24T15:30:45Z');
1134 $tm->strftime('%f'); # ''
1135 $tm->strftime('%3f'); # ''
1136
1137 %3f is replaced by decimal point and exactly three fractional digits
1138 (zero-padded on the right or truncated if needed) if fractional
1139 seconds are present.
1140
1141 *This conversion specification is an extension to the "IEEE Std
1142 1003.1"
1143 <http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.
1144 html>*.
1145
1146 %F Equivalent to "%Y-%m-%d".
1147
1148 %g Replaced by the last 2 digits of the year of the week as a decimal
1149 number [00, 99].
1150
1151 %G Replaced by the week-based year as a decimal number [0001, 9999].
1152
1153 %h Equivalent to %b.
1154
1155 %H Replaced by the hour of day (24-hour clock) as a decimal number [00,
1156 23].
1157
1158 %I Replaced by the hour of day (12-hour clock) as a decimal number [01,
1159 12].
1160
1161 %j Replaced by the day of the year as a decimal number [001, 366].
1162
1163 %k Replaced by the hour of day (24-hour clock) as a decimal number [1,
1164 23]; a single digit is preceded by a space.
1165
1166 *This conversion specification is an extension to the "IEEE Std
1167 1003.1"
1168 <http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.
1169 html>*.
1170
1171 %l Replaced by the hour of day (12-hour clock) as a decimal number [1,
1172 12]; a single digit is preceded by a space.
1173
1174 *This conversion specification is an extension to the "IEEE Std
1175 1003.1"
1176 <http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.
1177 html>*.
1178
1179 %m Replaced by the month of the year as a decimal number [01, 12].
1180
1181 %M Replaced by the minute of hour as a decimal number [00, 59].
1182
1183 %n Replaced by a <newline> character.
1184
1185 %N Replaced by the fractional second as a decimal number. This
1186 conversion specification permits use of an optional maximum field
1187 width [0, 9] where the default field width of 0 will use the
1188 shortest of the following representations:
1189
1190 fff (millisecond)
1191 ffffff (microsecond)
1192 fffffffff (nanosecond)
1193
1194 Example:
1195
1196 $tm = Time::Moment->from_string('2012-12-24T15:30:45.123456Z');
1197 $tm->strftime('%N'); # '123456'
1198 $tm->strftime('%3N'); # '123'
1199 $tm->strftime('%9N'); # '123456000'
1200
1201 %3N is replaced by exactly three fractional digits (zero-padded on
1202 the right or truncated if needed).
1203
1204 *This conversion specification is an extension to the "IEEE Std
1205 1003.1"
1206 <http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.
1207 html>*.
1208
1209 %p Replaced by the C locale's meridian notation. Example: AM, PM.
1210
1211 %r Replaced by the C locale's time in a.m. and p.m. notation.
1212 Equivalent to "%I:%M:%S %p".
1213
1214 %R Replaced by the time in 24-hour notation. Equivalent to "%H:%M".
1215
1216 %s Replaced by the number of seconds from the epoch of
1217 1970-01-01T00:00:00Z as a decimal number.
1218
1219 *This conversion specification is an extension to the "IEEE Std
1220 1003.1"
1221 <http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.
1222 html>*.
1223
1224 %S Replaced by the second of hour as a decimal number [00, 59].
1225
1226 %t Replaced by a <tab> character.
1227
1228 %T Replaced by the time of day. Equivalent to "%H:%M:%S".
1229
1230 %u Replaced by the day of the week as a decimal number [1, 7], with 1
1231 representing Monday.
1232
1233 %U Replaced by the week number of the year as a decimal number [00,
1234 53]. The first Sunday of January is the first day of week 1; days in
1235 the new year before this are in week 0.
1236
1237 %V Replaced by the week number of the year (Monday as the first day of
1238 the week) as a decimal number [01, 53]. If the week containing 1
1239 January has four or more days in the new year, then it is considered
1240 week 1. Otherwise, it is the last week of the previous year, and the
1241 next week is week 1. Both January 4th and the first Thursday of
1242 January are always in week 1.
1243
1244 %w Replaced by the day of the week as a decimal number [0, 6], with 0
1245 representing Sunday.
1246
1247 %W Replaced by the week number of the year as a decimal number [00,
1248 53]. The first Monday of January is the first day of week 1; days in
1249 the new year before this are in week 0.
1250
1251 %x Replaced by the C locale's date representation. Equivalent to
1252 "%m/%d/%y".
1253
1254 %X Replaced by the C locale's time representation. Equivalent to
1255 "%H:%M:%S".
1256
1257 %y Replaced by the last two digits of the year as a decimal number [00,
1258 99].
1259
1260 %Y Replaced by the year as a decimal number [0001, 9999].
1261
1262 %z Replaced by the offset from UTC in the ISO 8601 basic format
1263 (±hhmm).
1264
1265 %:z Replaced by the offset from UTC in the ISO 8601 extended format
1266 (±hh:mm).
1267
1268 %Z Replaced by the offset from UTC in the ISO 8601 extended format or
1269 by UTC designator (±hh:mm or Z).
1270
1271 "%%"
1272 Replaced by %.
1273
1274 length_of_year
1275 $integer = $tm->length_of_year;
1276
1277 Returns the length of the year in days [365, 366].
1278
1279 length_of_quarter
1280 $integer = $tm->length_of_quarter;
1281
1282 Returns the length of the quarter of the year in days [90, 92].
1283
1284 length_of_month
1285 $integer = $tm->length_of_month;
1286
1287 Returns the length of the month of the year in days [28, 31].
1288
1289 length_of_week_year
1290 $integer = $tm->length_of_week_year;
1291
1292 Returns the length of the week of the year in weeks [52, 53].
1293
1294 utc_rd_values
1295 ($rdn, $sod, $nanosecond) = $tm->utc_rd_values;
1296
1297 Returns a list of three elements:
1298
1299 $rdn
1300 The number of integral days from the Rata Die epoch of 0000-12-31.
1301
1302 $sod
1303 The second of the day [0, 86_399].
1304
1305 $nanosecond
1306 The nanosecond of the second [0, 999_999_999].
1307
1308 utc_rd_as_seconds
1309 $seconds = $tm->utc_rd_as_seconds;
1310
1311 Returns the number of integral seconds from the Rata Die epoch of
1312 0000-12-31T00:00:00Z.
1313
1314 local_rd_values
1315 ($rdn, $sod, $nanosecond) = $tm->local_rd_values;
1316
1317 Returns a list of three elements:
1318
1319 $rdn
1320 The number of integral days from the Rata Die epoch of 0000-12-31.
1321
1322 $sod
1323 The second of the day [0, 86_399].
1324
1325 $nanosecond
1326 The nanosecond of the second [0, 999_999_999].
1327
1328 local_rd_as_seconds
1329 $seconds = $tm->local_rd_as_seconds;
1330
1331 Returns the number of integral seconds from the Rata Die epoch of
1332 0000-12-31T00:00:00.
1333
1334OVERLOADED OPERATORS
1335 stringification
1336 $string = "$tm";
1337
1338 The $string will be in one of the following representations:
1339
1340 YYYY-MM-DDThh:mm:ss
1341 YYYY-MM-DDThh:mm:ss.fff
1342 YYYY-MM-DDThh:mm:ss.ffffff
1343 YYYY-MM-DDThh:mm:ss.fffffffff
1344
1345 Followed by a zone designator in one of the following representations:
1346
1347 Z
1348 ±hh:mm
1349
1350 The shortest representation will be used where the omitted parts are
1351 implied to be zero. This representation is conformant with ISO 8601
1352 profiles, such as:
1353
1354 * RFC 3339 Date and Time on the Internet: Timestamps
1355 <http://tools.ietf.org/html/rfc3339>
1356
1357 * RFC 4287 The Atom Syndication Format
1358 <http://tools.ietf.org/html/rfc4287#section-3.3>
1359
1360 * W3C Date and Time Formats <http://www.w3.org/TR/NOTE-datetime>
1361
1362 * HTML5
1363 <http://www.w3.org/TR/html5/infrastructure.html#global-dates-and-tim
1364 es>
1365
1366 * XML Schema <http://www.w3.org/TR/xmlschema-2/#dateTime>
1367
1368 The "to_string" method or the "strftime" format string
1369 "%Y-%m-%dT%H:%M:%S%f%Z" produces an equivalent string representation:
1370
1371 "$tm" eq $tm->to_string;
1372 "$tm" eq $tm->strftime("%Y-%m-%dT%H:%M:%S%f%Z");
1373
1374 The total length of the string representation will be between 20 and 35
1375 characters (inclusive).
1376
1377 comparison
1378 $integer = $tm1 <=> $tm2;
1379
1380 $boolean = $tm1 == $tm2;
1381 $boolean = $tm1 != $tm2;
1382 $boolean = $tm1 < $tm2;
1383 $boolean = $tm1 > $tm2;
1384 $boolean = $tm1 <= $tm2;
1385 $boolean = $tm1 >= $tm2;
1386
1387SERIALIZATION
1388 Storable
1389 The serialized representation of a "Time::Moment" is a string of 16
1390 bytes that contains MAGIC (2 bytes), time zone offset from UTC (2
1391 bytes), the number of days from Rata Die (4 bytes), second of the day (4
1392 bytes) and nanosecond of the second (4 bytes).
1393
1394 The total size of the serialized "Time::Moment" instance using "nfreeze"
1395 is 34 bytes.
1396
1397 JSON
1398 "Time::Moment" implements a "TO_JSON" method that returns the
1399 stringified representation of the instance.
1400
1401 CBOR
1402 "Time::Moment" implements a "TO_CBOR" method that returns the
1403 stringified representation of the instance using tag 0 (*standard
1404 date/time string*).
1405
1406 See CBOR::XS, RFC 7049 Section 2.4.1
1407 <http://tools.ietf.org/html/rfc7049#section-2.4.1> and "eg/cbor.pl" for
1408 an example how to roundtrip instances of "Time::Moment".
1409
1410 Sereal
1411 Sereal version 2.030 or later implements support for the generic
1412 serialization protocol "FREEZE/THAW".
1413
1414 FREEZE/THAW
1415 "Time::Moment" implements a "FREEZE" method that returns the stringified
1416 representation of the instance and a "THAW" method according to the
1417 serialization protocol specified in Types::Serialiser.
1418
1419EXAMPLE FORMAT STRINGS
1420 ISO 8601 - Data elements and interchange formats
1421 Date
1422 Calendar date - 24 December 2012
1423
1424 Basic format: Example:
1425 %Y%m%d 20121224
1426 %y%m 201212 (reduced accuracy)
1427
1428 Extended format: Example:
1429 %Y-%m-%d 2012-12-24
1430 %Y-%m 2012-12 (reduced accuracy)
1431
1432 Ordinal date - 24 December 2012
1433
1434 Basic format: Example:
1435 %Y%j 2012359
1436
1437 Extended format: Example:
1438 %Y-%j 2012-359
1439
1440 Week date - Monday, 24 December 2012
1441
1442 Basic format: Example:
1443 %GW%V%u 2012W521
1444 %GW%V 2012W52 (reduced accuracy)
1445
1446 Extended format: Example:
1447 %G-W%V-%u 2012-W52-1
1448 %G-W%V 2012-W52 (reduced accuracy)
1449
1450 Time of day
1451 Local time - 30 minutes and 45 seconds past 15 hours
1452
1453 Basic format: Example:
1454 %H%M%S 153045
1455 %H%M 1530 (reduced accuracy)
1456
1457 Extended format: Example:
1458 %H:%M:%S 15:30:45
1459 %H:%M 15:30 (reduced accuracy)
1460
1461 Local time with decimal fractions - 30 minutes and 45 and a half second
1462 past 15 hours
1463
1464 Basic format: Example:
1465 %H%M%S%f 153045.500
1466 %H%M%S.%1N 153045.5
1467
1468 Extended format: Example:
1469 %H:%M:%S%f 15:30:45.500
1470 %H:%M:%S.%1N 15:30:45.5
1471
1472 Local time and the difference from UTC - 30 minutes and 45 seconds past
1473 15 hours, one hour ahead of UTC
1474
1475 Basic format: Example:
1476 %H%M%S%z 153045+0100
1477
1478 Extended format: Example:
1479 %H:%M:%S%Z 15:30:45+01:00
1480
1481 Date and time of day
1482 Combinations of calendar date and time of day
1483
1484 Basic format: Example:
1485 %Y%m%dT%H%M%S%z 20121224T153045+0100
1486 %Y%m%dT%H%M%S%f%z 20121224T153045.500+0100
1487 %Y%m%dT%H%M%z 20121224T1530+0100 (reduced accuracy)
1488
1489 Extended format: Example:
1490 %Y-%m-%dT%H:%M:%S%Z 2012-12-24T15:30:45+01:00
1491 %Y-%m-%dT%H:%M:%S%f%Z 2012-12-24T15:30:45.500+01:00
1492 %Y-%m-%dT%H:%M%Z 2012-12-24T15:30+01:00 (reduced accuracy)
1493
1494 Combinations of ordinal date and time of day
1495
1496 Basic format: Example:
1497 %Y%jT%H%M%S%z 2012359T153045+0100
1498 %Y%jT%H%M%S%f%z 2012359T153045.500+0100
1499 %Y%jT%H%M%z 2012359T1530+0100 (reduced accuracy)
1500
1501 Extended format: Example:
1502 %Y-%jT%H:%M:%S%Z 2012-359T15:30:45+01:00
1503 %Y-%jT%H:%M:%S%f%Z 2012-359T15:30:45.500+01:00
1504 %Y-%jT%H:%M%Z 2012-359T15:30+01:00 (reduced accuracy)
1505
1506 Combinations of week date and time of day
1507
1508 Basic format: Example:
1509 %GW%V%uT%H%M%S%z 2012W521T153045+0100
1510 %GW%V%uT%H%M%S%f%z 2012W521T153045.500+0100
1511 %GW%V%uT%H%M%f%z 2012W521T1530+0100 (reduced accuracy)
1512
1513 Extended format: Example:
1514 %G-W%V-%uT%H:%M:%S%Z 2012-W52-1T15:30:45+01:00
1515 %G-W%V-%uT%H:%M:%S%f%Z 2012-W52-1T15:30:45.500+01:00
1516 %G-W%V-%uT%H:%M%Z 2012-W52-1T15:30+01:00 (reduced accuracy)
1517
1518 ISO 9075 - Information technology - Database languages - SQL
1519 Literal values from Part 2: Foundation (SQL/Foundation)
1520
1521 Date: Example:
1522 %Y-%m-%d 2012-12-24
1523
1524 Time: Example:
1525 %H:%M:%S 15:30:45
1526 %H:%M:%S%f 15:30:45.500
1527
1528 Timestamp: Example:
1529 %Y-%m-%d %H:%M:%S 2012-12-24 15:30:45
1530 %Y-%m-%d %H:%M:%S %:z 2012-12-24 15:30:45 +01:00
1531 %Y-%m-%d %H:%M:%S%f 2012-12-24 15:30:45.500
1532 %Y-%m-%d %H:%M:%S%f %:z 2012-12-24 15:30:45.500 +01:00
1533
1534 RFC 1123 - Requirements for Internet Hosts
1535 RFC 822 <http://tools.ietf.org/html/rfc822#section-5> as updated by RFC
1536 1123 <http://tools.ietf.org/html/rfc1123>.
1537
1538 Format: Example:
1539 %a, %d %b %Y %H:%M:%S %z Mon, 24 Dec 2012 15:30:45 +0100
1540
1541 RFC 2616 - HTTP/1.1
1542 RFC 2616 - 3.3.1 Full Date
1543 <http://tools.ietf.org/html/rfc2616#section-3.3.1>.
1544
1545 Format: Example:
1546 %a, %d %b %Y %H:%M:%S GMT Mon, 24 Dec 2012 14:30:45 GMT
1547
1548 An HTTP date value represents time as an instance of UTC:
1549
1550 $string = $tm->at_utc->strftime("%a, %d %b %Y %H:%M:%S GMT");
1551
1552 RFC 5322 - Internet Message Format
1553 RFC 5322 - 3.3. Date and Time Specification
1554 <http://tools.ietf.org/html/rfc5322#section-3.3>.
1555
1556 Format: Example:
1557 %a, %d %b %Y %H:%M:%S %z Mon, 24 Dec 2012 15:30:45 +0100
1558 %a, %d %b %Y %H:%M %z Mon, 24 Dec 2012 15:30 +0100
1559 %d %b %Y %H:%M:%S %z 24 Dec 2012 15:30:45 +0100
1560 %d %b %Y %H:%M %z 24 Dec 2012 15:30 +0100
1561
1562TIME ZONES
1563 An instance of "Time::Moment" represents an unambiguous point in time,
1564 but it's not time zone aware. When performing arithmetic on the local
1565 date/time or altering the components of the local date/time it may be
1566 necessary to use a time zone to convert to the correct representation.
1567
1568 "Time::Moment" is API compatible with DateTime::TimeZone and
1569 DateTime::TimeZone::Tzfile.
1570
1571 Converting from instant time to designated time zone
1572 $tm = Time::Moment->new(
1573 year => 2012,
1574 month => 12,
1575 day => 24,
1576 hour => 15
1577 );
1578 $zone = DateTime::TimeZone->new(name => 'America/New_York');
1579 $offset = $zone->offset_for_datetime($tm) / 60;
1580
1581 say $tm->with_offset_same_instant($offset); # 2012-12-24T10-05
1582
1583 Converting from local time to designated time zone
1584 $tm = Time::Moment->new(
1585 year => 2012,
1586 month => 12,
1587 day => 24,
1588 hour => 15
1589 );
1590 $zone = DateTime::TimeZone->new(name => 'America/New_York');
1591 $offset = $zone->offset_for_local_datetime($tm) / 60;
1592
1593 say $tm->with_offset_same_local($offset); # 2012-12-24T15-05
1594
1595 The Effect of Daylight Saving Time
1596 The time zone *Europe/Brussels* has 01:00 UTC as standard time, and
1597 02:00 UTC as daylight savings time, with transition dates according to
1598 the European Summer Time
1599 <http://en.wikipedia.org/wiki/Summer_Time_in_Europe>.
1600
1601 $zone = DateTime::TimeZone->new(name => 'Europe/Brussels');
1602
1603 sub convert_from_instant {
1604 my ($tm, $zone) = @_;
1605 my $offset = $zone->offset_for_datetime($tm) / 60;
1606 return $tm->with_offset_same_instant($offset);
1607 }
1608
1609 sub convert_from_local {
1610 my ($tm, $zone) = @_;
1611 my $offset = $zone->offset_for_local_datetime($tm) / 60;
1612 return $tm->with_offset_same_local($offset);
1613 }
1614
1615 European Summer Time begins (clocks go forward) at 01:00 UTC on the last
1616 Sunday in March, in 2014 the transition date was March 30.
1617
1618 $tm1 = Time::Moment->from_string('2014-03-29T12+01');
1619 $tm2 = $tm1->plus_hours(24);
1620 say convert_from_instant($tm2, $zone); # 2014-03-30T13+02
1621 say convert_from_local($tm2, $zone); # 2014-03-30T12+02
1622
1623 During the transition from standard time to daylight savings time, the
1624 local time interval between 02:00:00 and 02:59:59 does not exist. Local
1625 time values in that interval are invalid. "DateTime::TimeZone" raises an
1626 exception when attempting to convert non-existing local time.
1627
1628 $tm1 = Time::Moment->from_string('2014-03-29T22+01');
1629 $tm2 = $tm1->plus_hours(4);
1630 say convert_from_instant($tm2, $zone); # 2014-03-30T03+02
1631 say convert_from_local($tm2, $zone); # raises an exception
1632
1633 European Summer Time ends (clocks go backward) at 01:00 UTC on the last
1634 Sunday in October, in 2014 the transition date was October 26.
1635
1636 $tm1 = Time::Moment->from_string('2014-10-25T12+02');
1637 $tm2 = $tm1->plus_hours(24);
1638 say convert_from_instant($tm2, $zone); # 2014-10-26T11+01
1639 say convert_from_local($tm2, $zone); # 2014-10-26T12+01
1640
1641 During the transition from daylight savings time to standard time, the
1642 local time interval between 02:00:00 and 02:59:59 is repeated. Local
1643 time values in that interval are ambiguous because they occur twice.
1644 When "DateTime::TimeZone" converts an ambiguous local time it returns
1645 the numerically lowest offset (usually the standard one).
1646
1647 $tm1 = Time::Moment->from_string('2014-10-25T22+02');
1648 $tm2 = $tm1->plus_hours(4);
1649 say convert_from_instant($tm2, $zone); # 2014-10-26T02+02
1650 say convert_from_local($tm2, $zone); # 2014-10-26T02+01
1651
1652DIAGNOSTICS
1653 (F) Usage: %s
1654 Method called with wrong number of arguments.
1655
1656 (F) Parameter '%s' is out of range
1657 (F) Parameter '%s' is out of the range [%d, %d]
1658 (F) Cannot coerce object of type %s to Time::Moment
1659 (F) Could not parse the given string
1660 (F) %s is not an instance of Time::Moment
1661 (F) A %s object can only be compared to another %s object ('%s', '%s')
1662
1663THREAD SAFETY
1664 "Time::Moment" is thread safe.
1665
1666SEE ALSO
1667 DateTime
1668
1669 Time::Piece
1670
1671SUPPORT
1672 Bugs / Feature Requests
1673 Please report any bugs or feature requests through the issue tracker at
1674 <https://github.com/chansen/p5-time-moment/issues>. You will be notified
1675 automatically of any progress on your issue.
1676
1677 SOURCE CODE
1678 This is open source software. The code repository is available for
1679 public review and contribution under the terms of the license.
1680
1681 <https://github.com/chansen/p5-time-moment>
1682
1683 git clone https://github.com/chansen/p5-time-moment
1684
1685AUTHOR
1686 Christian Hansen "chansen@cpan.org"
1687
1688COPYRIGHT
1689 Copyright 2013-2017 by Christian Hansen.
1690
1691 This is free software; you can redistribute it and/or modify it under
1692 the same terms as the Perl 5 programming language system itself.
1693
1694