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