1Time::Piece(3pm)       Perl Programmers Reference Guide       Time::Piece(3pm)
2
3
4

NAME

6       Time::Piece - Object Oriented time objects
7

SYNOPSIS

9           use Time::Piece;
10
11           my $t = localtime;
12           print "Time is $t\n";
13           print "Year is ", $t->year, "\n";
14

DESCRIPTION

16       This module replaces the standard "localtime" and "gmtime" functions
17       with implementations that return objects. It does so in a backwards
18       compatible manner, so that using localtime/gmtime in the way documented
19       in perlfunc will still return what you expect.
20
21       The module actually implements most of an interface described by Larry
22       Wall on the perl5-porters mailing list here:
23       <https://www.nntp.perl.org/group/perl.perl5.porters/2000/01/msg5283.html>
24

USAGE

26       After importing this module, when you use localtime or gmtime in a
27       scalar context, rather than getting an ordinary scalar string
28       representing the date and time, you get a Time::Piece object, whose
29       stringification happens to produce the same effect as the localtime and
30       gmtime functions. There is also a new() constructor provided, which is
31       the same as localtime(), except when passed a Time::Piece object, in
32       which case it's a copy constructor. The following methods are available
33       on the object:
34
35           $t->sec                 # also available as $t->second
36           $t->min                 # also available as $t->minute
37           $t->hour                # 24 hour
38           $t->mday                # also available as $t->day_of_month
39           $t->mon                 # 1 = January
40           $t->_mon                # 0 = January
41           $t->monname             # Feb
42           $t->month               # same as $t->monname
43           $t->fullmonth           # February
44           $t->year                # based at 0 (year 0 AD is, of course 1 BC)
45           $t->_year               # year minus 1900
46           $t->yy                  # 2 digit year
47           $t->wday                # 1 = Sunday
48           $t->_wday               # 0 = Sunday
49           $t->day_of_week         # 0 = Sunday
50           $t->wdayname            # Tue
51           $t->day                 # same as wdayname
52           $t->fullday             # Tuesday
53           $t->yday                # also available as $t->day_of_year, 0 = Jan 01
54           $t->isdst               # also available as $t->daylight_savings
55
56           $t->hms                 # 12:34:56
57           $t->hms(".")            # 12.34.56
58           $t->time                # same as $t->hms
59
60           $t->ymd                 # 2000-02-29
61           $t->date                # same as $t->ymd
62           $t->mdy                 # 02-29-2000
63           $t->mdy("/")            # 02/29/2000
64           $t->dmy                 # 29-02-2000
65           $t->dmy(".")            # 29.02.2000
66           $t->datetime            # 2000-02-29T12:34:56 (ISO 8601)
67           $t->cdate               # Tue Feb 29 12:34:56 2000
68           "$t"                    # same as $t->cdate
69
70           $t->epoch               # seconds since the epoch
71           $t->tzoffset            # timezone offset in a Time::Seconds object
72
73           $t->julian_day          # number of days since Julian period began
74           $t->mjd                 # modified Julian date (JD-2400000.5 days)
75
76           $t->week                # week number (ISO 8601)
77
78           $t->is_leap_year        # true if it's a leap year
79           $t->month_last_day      # 28-31
80
81           $t->time_separator($s)  # set the default separator (default ":")
82           $t->date_separator($s)  # set the default separator (default "-")
83           $t->day_list(@days)     # set the default weekdays
84           $t->mon_list(@days)     # set the default months
85
86           $t->strftime(FORMAT)    # same as POSIX::strftime (without the overhead
87                                   # of the full POSIX extension)
88           $t->strftime()          # "Tue, 29 Feb 2000 12:34:56 GMT"
89
90           Time::Piece->strptime(STRING, FORMAT)
91                                   # see strptime man page. Creates a new
92                                   # Time::Piece object
93
94       Note that "localtime" and "gmtime" are not listed above.  If called as
95       methods on a Time::Piece object, they act as constructors, returning a
96       new Time::Piece object for the current time.  In other words: they're
97       not useful as methods.
98
99   Local Locales
100       Both wdayname (day) and monname (month) allow passing in a list to use
101       to index the name of the days against. This can be useful if you need
102       to implement some form of localisation without actually installing or
103       using locales. Note that this is a global override and will affect all
104       Time::Piece instances.
105
106         my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
107
108         my $french_day = localtime->day(@days);
109
110       These settings can be overridden globally too:
111
112         Time::Piece::day_list(@days);
113
114       Or for months:
115
116         Time::Piece::mon_list(@months);
117
118       And locally for months:
119
120         print localtime->month(@months);
121
122       Or to populate with your current system locale call:
123           Time::Piece->use_locale();
124
125   Date Calculations
126       It's possible to use simple addition and subtraction of objects:
127
128           use Time::Seconds;
129
130           my $seconds = $t1 - $t2;
131           $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
132
133       The following are valid ($t1 and $t2 are Time::Piece objects):
134
135           $t1 - $t2; # returns Time::Seconds object
136           $t1 - 42; # returns Time::Piece object
137           $t1 + 533; # returns Time::Piece object
138
139       However adding a Time::Piece object to another Time::Piece object will
140       cause a runtime error.
141
142       Note that the first of the above returns a Time::Seconds object, so
143       while examining the object will print the number of seconds (because of
144       the overloading), you can also get the number of minutes, hours, days,
145       weeks and years in that delta, using the Time::Seconds API.
146
147       In addition to adding seconds, there are two APIs for adding months and
148       years:
149
150           $t = $t->add_months(6);
151           $t = $t->add_years(5);
152
153       The months and years can be negative for subtractions. Note that there
154       is some "strange" behaviour when adding and subtracting months at the
155       ends of months. Generally when the resulting month is shorter than the
156       starting month then the number of overlap days is added. For example
157       subtracting a month from 2008-03-31 will not result in 2008-02-31 as
158       this is an impossible date. Instead you will get 2008-03-02. This
159       appears to be consistent with other date manipulation tools.
160
161   Truncation
162       Calling the "truncate" method returns a copy of the object but with the
163       time truncated to the start of the supplied unit.
164
165           $t = $t->truncate(to => 'day');
166
167       This example will set the time to midnight on the same date which $t
168       had previously. Allowed values for the "to" parameter are: "year",
169       "quarter", "month", "day", "hour", "minute" and "second".
170
171   Date Comparisons
172       Date comparisons are also possible, using the full suite of "<", ">",
173       "<=", ">=", "<=>", "==" and "!=".
174
175   Date Parsing
176       Time::Piece has a built-in strptime() function (from FreeBSD), allowing
177       you incredibly flexible date parsing routines. For example:
178
179         my $t = Time::Piece->strptime("Sunday 3rd Nov, 1943",
180                                       "%A %drd %b, %Y");
181
182         print $t->strftime("%a, %d %b %Y");
183
184       Outputs:
185
186         Wed, 03 Nov 1943
187
188       (see, it's even smart enough to fix my obvious date bug)
189
190       For more information see "man strptime", which should be on all unix
191       systems.
192
193       Alternatively look here:
194       <http://www.unix.com/man-page/FreeBSD/3/strftime/>
195
196       CAVEAT %A, %a, %B, %b, and friends
197
198       Time::Piece::strptime by default can only parse American English date
199       names.  Meanwhile, Time::Piece->strftime() will return date names that
200       use the current configured system locale. This means dates returned by
201       strftime might not be able to be parsed by strptime. This is the
202       default behavior and can be overridden by calling
203       Time::Piece->use_locale(). This builds a list of the current locale's
204       day and month names which strptime will use to parse with.  Note this
205       is a global override and will affect all Time::Piece instances.
206
207       For instance with a German locale:
208
209           localtime->day_list();
210
211       Returns
212
213           ( 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' )
214
215       While:
216
217           Time::Piece->use_locale();
218           localtime->day_list();
219
220       Returns
221
222           ( 'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa' )
223
224   YYYY-MM-DDThh:mm:ss
225       The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the
226       time format to be hh:mm:ss (24 hour clock), and if combined, they
227       should be concatenated with date first and with a capital 'T' in front
228       of the time.
229
230   Week Number
231       The week number may be an unknown concept to some readers.  The ISO
232       8601 standard defines that weeks begin on a Monday and week 1 of the
233       year is the week that includes both January 4th and the first Thursday
234       of the year.  In other words, if the first Monday of January is the
235       2nd, 3rd, or 4th, the preceding days of the January are part of the
236       last week of the preceding year.  Week numbers range from 1 to 53.
237
238   Global Overriding
239       Finally, it's possible to override localtime and gmtime everywhere, by
240       including the ':override' tag in the import list:
241
242           use Time::Piece ':override';
243

CAVEATS

245   Setting $ENV{TZ} in Threads on Win32
246       Note that when using perl in the default build configuration on Win32
247       (specifically, when perl is built with PERL_IMPLICIT_SYS), each perl
248       interpreter maintains its own copy of the environment and only the main
249       interpreter will update the process environment seen by strftime.
250
251       Therefore, if you make changes to $ENV{TZ} from inside a thread other
252       than the main thread then those changes will not be seen by strftime if
253       you subsequently call that with the %Z formatting code. You must change
254       $ENV{TZ} in the main thread to have the desired effect in this case
255       (and you must also call _tzset() in the main thread to register the
256       environment change).
257
258       Furthermore, remember that this caveat also applies to fork(), which is
259       emulated by threads on Win32.
260
261   Use of epoch seconds
262       This module internally uses the epoch seconds system that is provided
263       via the perl time() function and supported by gmtime() and localtime().
264
265       If your perl does not support times larger than "2^31" seconds then
266       this module is likely to fail at processing dates beyond the year 2038.
267       There are moves afoot to fix that in perl. Alternatively use 64 bit
268       perl. Or if none of those are options, use the DateTime module which
269       has support for years well into the future and past.
270
271       Also, the internal representation of Time::Piece->strftime deviates
272       from the standard POSIX implementation in that is uses the epoch
273       (instead of separate year, month, day parts). This change was added in
274       version 1.30. If you must have a more traditional strftime (which will
275       normally never calculate day light saving times correctly), you can
276       pass the date parts from Time::Piece into the strftime function
277       provided by the POSIX module (see strftime in POSIX ).
278

AUTHOR

280       Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while
281       creating Time::Piece for core perl)
282
284       Copyright 2001, Larry Wall.
285
286       This module is free software, you may distribute it under the same
287       terms as Perl.
288

SEE ALSO

290       The excellent Calendar FAQ at
291       <http://www.tondering.dk/claus/calendar.html>
292

BUGS

294       The test harness leaves much to be desired. Patches welcome.
295
296
297
298perl v5.38.2                      2023-11-30                  Time::Piece(3pm)
Impressum