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