Debian Codegraph @

upstream/debian-unstable/man3/Time::Piece.3perl

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