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 with
17       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       http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.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 its
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   Local Locales
95       Both wdayname (day) and monname (month) allow passing in a list to use
96       to index the name of the days against. This can be useful if you need
97       to implement some form of localisation without actually installing or
98       using locales.
99
100         my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
101
102         my $french_day = localtime->day(@days);
103
104       These settings can be overriden globally too:
105
106         Time::Piece::day_list(@days);
107
108       Or for months:
109
110         Time::Piece::mon_list(@months);
111
112       And locally for months:
113
114         print localtime->month(@months);
115
116   Date Calculations
117       It's possible to use simple addition and subtraction of objects:
118
119           use Time::Seconds;
120
121           my $seconds = $t1 - $t2;
122           $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
123
124       The following are valid ($t1 and $t2 are Time::Piece objects):
125
126           $t1 - $t2; # returns Time::Seconds object
127           $t1 - 42; # returns Time::Piece object
128           $t1 + 533; # returns Time::Piece object
129
130       However adding a Time::Piece object to another Time::Piece object will
131       cause a runtime error.
132
133       Note that the first of the above returns a Time::Seconds object, so
134       while examining the object will print the number of seconds (because of
135       the overloading), you can also get the number of minutes, hours, days,
136       weeks and years in that delta, using the Time::Seconds API.
137
138       In addition to adding seconds, there are two APIs for adding months and
139       years:
140
141           $t->add_months(6);
142           $t->add_years(5);
143
144       The months and years can be negative for subtractions. Note that there
145       is some "strange" behaviour when adding and subtracting months at the
146       ends of months. Generally when the resulting month is shorter than the
147       starting month then the number of overlap days is added. For example
148       subtracting a month from 2008-03-31 will not result in 2008-02-31 as
149       this is an impossible date. Instead you will get 2008-03-02. This
150       appears to be consistent with other date manipulation tools.
151
152   Date Comparisons
153       Date comparisons are also possible, using the full suite of "<", ">",
154       "<=", ">=", "<=>", "==" and "!=".
155
156   Date Parsing
157       Time::Piece links to your C library's strptime() function, allowing you
158       incredibly flexible date parsing routines. For example:
159
160         my $t = Time::Piece->strptime("Sun 3rd Nov, 1943",
161                                       "%A %drd %b, %Y");
162
163         print $t->strftime("%a, %d %b %Y");
164
165       Outputs:
166
167         Wed, 03 Nov 1943
168
169       (see, it's even smart enough to fix my obvious date bug)
170
171       For more information see "man strptime", which should be on all unix
172       systems.
173
174   YYYY-MM-DDThh:mm:ss
175       The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the
176       time format to be hh:mm:ss (24 hour clock), and if combined, they
177       should be concatenated with date first and with a capital 'T' in front
178       of the time.
179
180   Week Number
181       The week number may be an unknown concept to some readers.  The ISO
182       8601 standard defines that weeks begin on a Monday and week 1 of the
183       year is the week that includes both January 4th and the first Thursday
184       of the year.  In other words, if the first Monday of January is the
185       2nd, 3rd, or 4th, the preceding days of the January are part of the
186       last week of the preceding year.  Week numbers range from 1 to 53.
187
188   Global Overriding
189       Finally, it's possible to override localtime and gmtime everywhere, by
190       including the ':override' tag in the import list:
191
192           use Time::Piece ':override';
193

CAVEATS

195   Setting $ENV{TZ} in Threads on Win32
196       Note that when using perl in the default build configuration on Win32
197       (specifically, when perl is built with PERL_IMPLICIT_SYS), each perl
198       interpreter maintains its own copy of the environment and only the main
199       interpreter will update the process environment seen by strftime.
200
201       Therefore, if you make changes to $ENV{TZ} from inside a thread other
202       than the main thread then those changes will not be seen by strftime if
203       you subsequently call that with the %Z formatting code. You must change
204       $ENV{TZ} in the main thread to have the desired effect in this case
205       (and you must also call _tzset() in the main thread to register the
206       environment change).
207
208       Furthermore, remember that this caveat also applies to fork(), which is
209       emulated by threads on Win32.
210

AUTHOR

212       Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while
213       creating Time::Piece for core perl)
214

License

216       This module is free software, you may distribute it under the same
217       terms as Perl.
218

SEE ALSO

220       The excellent Calendar FAQ at
221       http://www.tondering.dk/claus/calendar.html
222

BUGS

224       The test harness leaves much to be desired. Patches welcome.
225
226
227
228perl v5.10.1                      2009-06-28                  Time::Piece(3pm)
Impressum