Debian Codegraph @

upstream/mageia-cauldron/man3pm/Time::Piece.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Time::Piece 3pm"
61 .TH Time::Piece 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Time::Piece \- Object Oriented time objects
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Time::Piece;
72 \&
73 \& my $t = localtime;
74 \& print "Time is $t\en";
75 \& print "Year is ", $t\->year, "\en";
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 This module replaces the standard \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR functions with
80 implementations that return objects. It does so in a backwards
81 compatible manner, so that using localtime/gmtime in the way documented
82 in perlfunc will still return what you expect.
83 .PP
84 The module actually implements most of an interface described by
85 Larry Wall on the perl5\-porters mailing list here:
86 <https://www.nntp.perl.org/group/perl.perl5.porters/2000/01/msg5283.html>
87 .SH USAGE
88 .IX Header "USAGE"
89 After importing this module, when you use localtime or gmtime in a scalar
90 context, rather than getting an ordinary scalar string representing the
91 date and time, you get a Time::Piece object, whose stringification happens
92 to produce the same effect as the localtime and gmtime functions. There is
93 also a \fBnew()\fR constructor provided, which is the same as \fBlocaltime()\fR, except
94 when passed a Time::Piece object, in which case it\*(Aqs a copy constructor. The
95 following methods are available on the object:
96 .PP
97 .Vb 10
98 \& $t\->sec # also available as $t\->second
99 \& $t\->min # also available as $t\->minute
100 \& $t\->hour # 24 hour
101 \& $t\->mday # also available as $t\->day_of_month
102 \& $t\->mon # 1 = January
103 \& $t\->_mon # 0 = January
104 \& $t\->monname # Feb
105 \& $t\->month # same as $t\->monname
106 \& $t\->fullmonth # February
107 \& $t\->year # based at 0 (year 0 AD is, of course 1 BC)
108 \& $t\->_year # year minus 1900
109 \& $t\->yy # 2 digit year
110 \& $t\->wday # 1 = Sunday
111 \& $t\->_wday # 0 = Sunday
112 \& $t\->day_of_week # 0 = Sunday
113 \& $t\->wdayname # Tue
114 \& $t\->day # same as wdayname
115 \& $t\->fullday # Tuesday
116 \& $t\->yday # also available as $t\->day_of_year, 0 = Jan 01
117 \& $t\->isdst # also available as $t\->daylight_savings
118 \&
119 \& $t\->hms # 12:34:56
120 \& $t\->hms(".") # 12.34.56
121 \& $t\->time # same as $t\->hms
122 \&
123 \& $t\->ymd # 2000\-02\-29
124 \& $t\->date # same as $t\->ymd
125 \& $t\->mdy # 02\-29\-2000
126 \& $t\->mdy("/") # 02/29/2000
127 \& $t\->dmy # 29\-02\-2000
128 \& $t\->dmy(".") # 29.02.2000
129 \& $t\->datetime # 2000\-02\-29T12:34:56 (ISO 8601)
130 \& $t\->cdate # Tue Feb 29 12:34:56 2000
131 \& "$t" # same as $t\->cdate
132 \&
133 \& $t\->epoch # seconds since the epoch
134 \& $t\->tzoffset # timezone offset in a Time::Seconds object
135 \&
136 \& $t\->julian_day # number of days since Julian period began
137 \& $t\->mjd # modified Julian date (JD\-2400000.5 days)
138 \&
139 \& $t\->week # week number (ISO 8601)
140 \&
141 \& $t\->is_leap_year # true if it\*(Aqs a leap year
142 \& $t\->month_last_day # 28\-31
143 \&
144 \& $t\->time_separator($s) # set the default separator (default ":")
145 \& $t\->date_separator($s) # set the default separator (default "\-")
146 \& $t\->day_list(@days) # set the default weekdays
147 \& $t\->mon_list(@days) # set the default months
148 \&
149 \& $t\->strftime(FORMAT) # same as POSIX::strftime (without the overhead
150 \& # of the full POSIX extension)
151 \& $t\->strftime() # "Tue, 29 Feb 2000 12:34:56 GMT"
152 \&
153 \& Time::Piece\->strptime(STRING, FORMAT)
154 \& # see strptime man page. Creates a new
155 \& # Time::Piece object
156 .Ve
157 .PP
158 Note that \f(CW\*(C`localtime\*(C'\fR and \f(CW\*(C`gmtime\*(C'\fR are not listed above. If called as
159 methods on a Time::Piece object, they act as constructors, returning a new
160 Time::Piece object for the current time. In other words: they\*(Aqre not useful as
161 methods.
162 .SS "Local Locales"
163 .IX Subsection "Local Locales"
164 Both wdayname (day) and monname (month) allow passing in a list to use
165 to index the name of the days against. This can be useful if you need
166 to implement some form of localisation without actually installing or
167 using locales. Note that this is a global override and will affect
168 all Time::Piece instances.
169 .PP
170 .Vb 1
171 \& my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
172 \&
173 \& my $french_day = localtime\->day(@days);
174 .Ve
175 .PP
176 These settings can be overridden globally too:
177 .PP
178 .Vb 1
179 \& Time::Piece::day_list(@days);
180 .Ve
181 .PP
182 Or for months:
183 .PP
184 .Vb 1
185 \& Time::Piece::mon_list(@months);
186 .Ve
187 .PP
188 And locally for months:
189 .PP
190 .Vb 1
191 \& print localtime\->month(@months);
192 .Ve
193 .PP
194 Or to populate with your current system locale call:
195 Time::Piece\->\fBuse_locale()\fR;
196 .SS "Date Calculations"
197 .IX Subsection "Date Calculations"
198 It\*(Aqs possible to use simple addition and subtraction of objects:
199 .PP
200 .Vb 1
201 \& use Time::Seconds;
202 \&
203 \& my $seconds = $t1 \- $t2;
204 \& $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
205 .Ve
206 .PP
207 The following are valid ($t1 and \f(CW$t2\fR are Time::Piece objects):
208 .PP
209 .Vb 3
210 \& $t1 \- $t2; # returns Time::Seconds object
211 \& $t1 \- 42; # returns Time::Piece object
212 \& $t1 + 533; # returns Time::Piece object
213 .Ve
214 .PP
215 However adding a Time::Piece object to another Time::Piece object
216 will cause a runtime error.
217 .PP
218 Note that the first of the above returns a Time::Seconds object, so
219 while examining the object will print the number of seconds (because
220 of the overloading), you can also get the number of minutes, hours,
221 days, weeks and years in that delta, using the Time::Seconds API.
222 .PP
223 In addition to adding seconds, there are two APIs for adding months and
224 years:
225 .PP
226 .Vb 2
227 \& $t = $t\->add_months(6);
228 \& $t = $t\->add_years(5);
229 .Ve
230 .PP
231 The months and years can be negative for subtractions. Note that there
232 is some "strange" behaviour when adding and subtracting months at the
233 ends of months. Generally when the resulting month is shorter than the
234 starting month then the number of overlap days is added. For example
235 subtracting a month from 2008\-03\-31 will not result in 2008\-02\-31 as this
236 is an impossible date. Instead you will get 2008\-03\-02. This appears to
237 be consistent with other date manipulation tools.
238 .SS Truncation
239 .IX Subsection "Truncation"
240 Calling the \f(CW\*(C`truncate\*(C'\fR method returns a copy of the object but with the
241 time truncated to the start of the supplied unit.
242 .PP
243 .Vb 1
244 \& $t = $t\->truncate(to => \*(Aqday\*(Aq);
245 .Ve
246 .PP
247 This example will set the time to midnight on the same date which \f(CW$t\fR
248 had previously. Allowed values for the "to" parameter are: "year",
249 "quarter", "month", "day", "hour", "minute" and "second".
250 .SS "Date Comparisons"
251 .IX Subsection "Date Comparisons"
252 Date comparisons are also possible, using the full suite of "<", ">",
253 "<=", ">=", "<=>", "==" and "!=".
254 .SS "Date Parsing"
255 .IX Subsection "Date Parsing"
256 Time::Piece has a built\-in \fBstrptime()\fR function (from FreeBSD), allowing
257 you incredibly flexible date parsing routines. For example:
258 .PP
259 .Vb 2
260 \& my $t = Time::Piece\->strptime("Sunday 3rd Nov, 1943",
261 \& "%A %drd %b, %Y");
262 \&
263 \& print $t\->strftime("%a, %d %b %Y");
264 .Ve
265 .PP
266 Outputs:
267 .PP
268 .Vb 1
269 \& Wed, 03 Nov 1943
270 .Ve
271 .PP
272 (see, it\*(Aqs even smart enough to fix my obvious date bug)
273 .PP
274 For more information see "man strptime", which should be on all unix
275 systems.
276 .PP
277 Alternatively look here: <http://www.unix.com/man\-page/FreeBSD/3/strftime/>
278 .PP
279 \fICAVEAT \fR\f(CI%A\fR\fI, \fR\f(CI%a\fR\fI, \fR\f(CI%B\fR\fI, \fR\f(CI%b\fR\fI, and friends\fR
280 .IX Subsection "CAVEAT %A, %a, %B, %b, and friends"
281 .PP
282 Time::Piece::strptime by default can only parse American English date names.
283 Meanwhile, Time::Piece\->\fBstrftime()\fR will return date names that use the current
284 configured system locale. This means dates returned by strftime might not be
285 able to be parsed by strptime. This is the default behavior and can be
286 overridden by calling Time::Piece\->\fBuse_locale()\fR. This builds a list of the
287 current locale\*(Aqs day and month names which strptime will use to parse with.
288 Note this is a global override and will affect all Time::Piece instances.
289 .PP
290 For instance with a German locale:
291 .PP
292 .Vb 1
293 \& localtime\->day_list();
294 .Ve
295 .PP
296 Returns
297 .PP
298 .Vb 1
299 \& ( \*(AqSun\*(Aq, \*(AqMon\*(Aq, \*(AqTue\*(Aq, \*(AqWed\*(Aq, \*(AqThu\*(Aq, \*(AqFri\*(Aq, \*(AqSat\*(Aq )
300 .Ve
301 .PP
302 While:
303 .PP
304 .Vb 2
305 \& Time::Piece\->use_locale();
306 \& localtime\->day_list();
307 .Ve
308 .PP
309 Returns
310 .PP
311 .Vb 1
312 \& ( \*(AqSo\*(Aq, \*(AqMo\*(Aq, \*(AqDi\*(Aq, \*(AqMi\*(Aq, \*(AqDo\*(Aq, \*(AqFr\*(Aq, \*(AqSa\*(Aq )
313 .Ve
314 .SS YYYY\-MM\-DDThh:mm:ss
315 .IX Subsection "YYYY-MM-DDThh:mm:ss"
316 The ISO 8601 standard defines the date format to be YYYY\-MM\-DD, and
317 the time format to be hh:mm:ss (24 hour clock), and if combined, they
318 should be concatenated with date first and with a capital \*(AqT\*(Aq in front
319 of the time.
320 .SS "Week Number"
321 .IX Subsection "Week Number"
322 The \fIweek number\fR may be an unknown concept to some readers. The ISO
323 8601 standard defines that weeks begin on a Monday and week 1 of the
324 year is the week that includes both January 4th and the first Thursday
325 of the year. In other words, if the first Monday of January is the
326 2nd, 3rd, or 4th, the preceding days of the January are part of the
327 last week of the preceding year. Week numbers range from 1 to 53.
328 .SS "Global Overriding"
329 .IX Subsection "Global Overriding"
330 Finally, it\*(Aqs possible to override localtime and gmtime everywhere, by
331 including the \*(Aq:override\*(Aq tag in the import list:
332 .PP
333 .Vb 1
334 \& use Time::Piece \*(Aq:override\*(Aq;
335 .Ve
336 .SH CAVEATS
337 .IX Header "CAVEATS"
338 .ie n .SS "Setting $ENV{TZ} in Threads on Win32"
339 .el .SS "Setting \f(CW$ENV\fP{TZ} in Threads on Win32"
340 .IX Subsection "Setting $ENV{TZ} in Threads on Win32"
341 Note that when using perl in the default build configuration on Win32
342 (specifically, when perl is built with PERL_IMPLICIT_SYS), each perl
343 interpreter maintains its own copy of the environment and only the main
344 interpreter will update the process environment seen by strftime.
345 .PP
346 Therefore, if you make changes to \f(CW$ENV\fR{TZ} from inside a thread other than
347 the main thread then those changes will not be seen by strftime if you
348 subsequently call that with the \f(CW%Z\fR formatting code. You must change \f(CW$ENV\fR{TZ}
349 in the main thread to have the desired effect in this case (and you must
350 also call \fB_tzset()\fR in the main thread to register the environment change).
351 .PP
352 Furthermore, remember that this caveat also applies to \fBfork()\fR, which is
353 emulated by threads on Win32.
354 .SS "Use of epoch seconds"
355 .IX Subsection "Use of epoch seconds"
356 This module internally uses the epoch seconds system that is provided via
357 the perl \f(CWtime()\fR function and supported by \f(CWgmtime()\fR and \f(CWlocaltime()\fR.
358 .PP
359 If your perl does not support times larger than \f(CW\*(C`2^31\*(C'\fR seconds then this
360 module is likely to fail at processing dates beyond the year 2038. There are
361 moves afoot to fix that in perl. Alternatively use 64 bit perl. Or if none
362 of those are options, use the DateTime module which has support for years
363 well into the future and past.
364 .PP
365 Also, the internal representation of Time::Piece\->strftime deviates from the
366 standard POSIX implementation in that is uses the epoch (instead of separate
367 year, month, day parts). This change was added in version 1.30. If you must
368 have a more traditional strftime (which will normally never calculate day
369 light saving times correctly), you can pass the date parts from Time::Piece
370 into the strftime function provided by the POSIX module
371 (see strftime in POSIX ).
372 .SH AUTHOR
373 .IX Header "AUTHOR"
374 Matt Sergeant, [email protected]
375 Jarkko Hietaniemi, [email protected] (while creating Time::Piece for core perl)
376 .SH "COPYRIGHT AND LICENSE"
377 .IX Header "COPYRIGHT AND LICENSE"
378 Copyright 2001, Larry Wall.
379 .PP
380 This module is free software, you may distribute it under the same terms
381 as Perl.
382 .SH "SEE ALSO"
383 .IX Header "SEE ALSO"
384 The excellent Calendar FAQ at <http://www.tondering.dk/claus/calendar.html>
385 .SH BUGS
386 .IX Header "BUGS"
387 The test harness leaves much to be desired. Patches welcome.