1Time::Moment(3)       User Contributed Perl Documentation      Time::Moment(3)
2
3
4

NAME

6       Time::Moment - Represents a date and time of day with an offset from
7       UTC
8

SYNOPSIS

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

DESCRIPTION

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

CONSTRUCTORS

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

INSTANCE METHODS

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

OVERLOADED 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 <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

SERIALIZATION

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

EXAMPLE FORMAT STRINGS

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

TIME ZONES

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

DIAGNOSTICS

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

THREAD SAFETY

1666       "Time::Moment" is thread safe.
1667

SEE ALSO

1669       DateTime
1670
1671       Time::Piece
1672

SUPPORT

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

AUTHOR

1688       Christian Hansen "chansen@cpan.org"
1689

COPYRIGHT

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.34.0                      2022-01-21                   Time::Moment(3)