1Time::Piece(3pm) Perl Programmers Reference Guide Time::Piece(3pm)
2
6 Time::Piece - Object Oriented time objects
7
9 use Time::Piece;
10 my $t = localtime;
12 print "Time is $t\n";
13 print "Year is ", $t->year, "\n";
14
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 The module actually implements most of an interface described by Larry
22 Wall on the perl5-porters mailing list here:
23 <http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.html>
24
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 $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 $t->hms # 12:34:56
57 $t->hms(".") # 12.34.56
58 $t->time # same as $t->hms
59 $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 $t->epoch # seconds since the epoch
71 $t->tzoffset # timezone offset in a Time::Seconds object
72 $t->julian_day # number of days since Julian period began
74 $t->mjd # modified Julian date (JD-2400000.5 days)
75 $t->week # week number (ISO 8601)
77 $t->is_leap_year # true if it's a leap year
79 $t->month_last_day # 28-31
80 $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 $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 Time::Piece->strptime(STRING, FORMAT)
91 # see strptime man page. Creates a new
92 # Time::Piece object
93 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 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 my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
107 my $french_day = localtime->day(@days);
109 These settings can be overridden globally too:
111 Time::Piece::day_list(@days);
113 Or for months:
115 Time::Piece::mon_list(@months);
117 And locally for months:
119 print localtime->month(@months);
121 Or to populate with your current system locale call:
123 Time::Piece->use_locale();
124 Date Calculations
126 It's possible to use simple addition and subtraction of objects:
127 use Time::Seconds;
129 my $seconds = $t1 - $t2;
131 $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
132 The following are valid ($t1 and $t2 are Time::Piece objects):
134 $t1 - $t2; # returns Time::Seconds object
136 $t1 - 42; # returns Time::Piece object
137 $t1 + 533; # returns Time::Piece object
138 However adding a Time::Piece object to another Time::Piece object will
140 cause a runtime error.
141 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 In addition to adding seconds, there are two APIs for adding months and
148 years:
149 $t = $t->add_months(6);
151 $t = $t->add_years(5);
152 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 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 $t = $t->truncate(to => 'day');
166 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 Date Comparisons
172 Date comparisons are also possible, using the full suite of "<", ">",
173 "<=", ">=", "<=>", "==" and "!=".
174 Date Parsing
176 Time::Piece has a built-in strptime() function (from FreeBSD), allowing
177 you incredibly flexible date parsing routines. For example:
178 my $t = Time::Piece->strptime("Sunday 3rd Nov, 1943",
180 "%A %drd %b, %Y");
181 print $t->strftime("%a, %d %b %Y");
183 Outputs:
185 Wed, 03 Nov 1943
187 (see, it's even smart enough to fix my obvious date bug)
189 For more information see "man strptime", which should be on all unix
191 systems.
192 Alternatively look here:
194 <http://www.unix.com/man-page/FreeBSD/3/strftime/>
195 CAVEAT %A, %a, %B, %b, and friends
197 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 For instance with a German locale:
208 localtime->day_list();
210 Returns
212 ( 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' )
214 While:
216 Time::Piece->use_locale();
218 localtime->day_list();
219 Returns
221 ( 'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa' )
223 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 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 Global Overriding
239 Finally, it's possible to override localtime and gmtime everywhere, by
240 including the ':override' tag in the import list:
241 use Time::Piece ':override';
243
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 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 Furthermore, remember that this caveat also applies to fork(), which is
259 emulated by threads on Win32.
260 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
264 "localtime()".
265 If your perl does not support times larger than "2^31" seconds then
267 this module is likely to fail at processing dates beyond the year 2038.
268 There are moves afoot to fix that in perl. Alternatively use 64 bit
269 perl. Or if none of those are options, use the DateTime module which
270 has support for years well into the future and past.
271
273 Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while
274 creating Time::Piece for core perl)
275
277 Copyright 2001, Larry Wall.
278 This module is free software, you may distribute it under the same
280 terms as Perl.
281
283 The excellent Calendar FAQ at
284 <http://www.tondering.dk/claus/calendar.html>
285
287 The test harness leaves much to be desired. Patches welcome.
288perl v5.30.2 2020-03-27 Time::Piece(3pm)