Time::Piece(3pm)

1Piece(3)              User Contributed Perl Documentation             Piece(3)
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 compati‐
18       ble manner, so that using localtime/gmtime in the way documented in
19       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/mail‐
24       ing-lists/perl5-porters/2000-01/msg00241.html
25

USAGE

27       After importing this module, when you use localtime or gmtime in a
28       scalar context, rather than getting an ordinary scalar string repre‐
29       senting the date and time, you get a Time::Piece object, whose stringi‐
30       fication happens to produce the same effect as the localtime and gmtime
31       functions. There is also a new() constructor provided, which is the
32       same as localtime(), except when passed a Time::Piece object, in which
33       case it's a copy constructor. The following methods are available on
34       the object:
35
36           $t->sec                 # also available as $t->second
37           $t->min                 # also available as $t->minute
38           $t->hour                # 24 hour
39           $t->mday                # also available as $t->day_of_month
40           $t->mon                 # 1 = January
41           $t->_mon                # 0 = January
42           $t->monname             # Feb
43           $t->month               # same as $t->monname
44           $t->fullmonth           # February
45           $t->year                # based at 0 (year 0 AD is, of course 1 BC)
46           $t->_year               # year minus 1900
47           $t->yy                  # 2 digit year
48           $t->wday                # 1 = Sunday
49           $t->_wday               # 0 = Sunday
50           $t->day_of_week         # 0 = Sunday
51           $t->wdayname            # Tue
52           $t->day                 # same as wdayname
53           $t->fullday             # Tuesday
54           $t->yday                # also available as $t->day_of_year, 0 = Jan 01
55           $t->isdst               # also available as $t->daylight_savings
56
57           $t->hms                 # 12:34:56
58           $t->hms(".")            # 12.34.56
59           $t->time                # same as $t->hms
60
61           $t->ymd                 # 2000-02-29
62           $t->date                # same as $t->ymd
63           $t->mdy                 # 02-29-2000
64           $t->mdy("/")            # 02/29/2000
65           $t->dmy                 # 29-02-2000
66           $t->dmy(".")            # 29.02.2000
67           $t->datetime            # 2000-02-29T12:34:56 (ISO 8601)
68           $t->cdate               # Tue Feb 29 12:34:56 2000
69           "$t"                    # same as $t->cdate
70
71           $t->epoch               # seconds since the epoch
72           $t->tzoffset            # timezone offset in a Time::Seconds object
73
74           $t->julian_day          # number of days since Julian period began
75           $t->mjd                 # modified Julian date (JD-2400000.5 days)
76
77           $t->week                # week number (ISO 8601)
78
79           $t->is_leap_year        # true if it its
80           $t->month_last_day      # 28-31
81
82           $t->time_separator($s)  # set the default separator (default ":")
83           $t->date_separator($s)  # set the default separator (default "-")
84           $t->day_list(@days)     # set the default weekdays
85           $t->mon_list(@days)     # set the default months
86
87           $t->strftime(FORMAT)    # same as POSIX::strftime (without the overhead
88                                   # of the full POSIX extension)
89           $t->strftime()          # "Tue, 29 Feb 2000 12:34:56 GMT"
90
91           Time::Piece->strptime(STRING, FORMAT)
92                                   # see strptime man page. Creates a new
93                                   # Time::Piece object
94
95       Local Locales
96
97       Both wdayname (day) and monname (month) allow passing in a list to use
98       to index the name of the days against. This can be useful if you need
99       to implement some form of localisation without actually installing or
100       using locales.
101
102         my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
103
104         my $french_day = localtime->day(@days);
105
106       These settings can be overriden globally too:
107
108         Time::Piece::day_list(@days);
109
110       Or for months:
111
112         Time::Piece::mon_list(@months);
113
114       And locally for months:
115
116         print localtime->month(@months);
117
118       Date Calculations
119
120       It's possible to use simple addition and subtraction of objects:
121
122           use Time::Seconds;
123
124           my $seconds = $t1 - $t2;
125           $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
126
127       The following are valid ($t1 and $t2 are Time::Piece objects):
128
129           $t1 - $t2; # returns Time::Seconds object
130           $t1 - 42; # returns Time::Piece object
131           $t1 + 533; # returns Time::Piece object
132
133       However adding a Time::Piece object to another Time::Piece object will
134       cause a runtime error.
135
136       Note that the first of the above returns a Time::Seconds object, so
137       while examining the object will print the number of seconds (because of
138       the overloading), you can also get the number of minutes, hours, days,
139       weeks and years in that delta, using the Time::Seconds API.
140
141       Date Comparisons
142
143       Date comparisons are also possible, using the full suite of "<", ">",
144       "<=", ">=", "<=>", "==" and "!=".
145
146       Date Parsing
147
148       Time::Piece links to your C library's strptime() function, allowing you
149       incredibly flexible date parsing routines. For example:
150
151         my $t = Time::Piece->strptime("Sun 3rd Nov, 1943",
152                                       "%A %drd %b, %Y");
153
154         print $t->strftime("%a, %d %b %Y");
155
156       Outputs:
157
158         Wed, 03 Nov 1943
159
160       (see, it's even smart enough to fix my obvious date bug)
161
162       For more information see "man strptime", which should be on all unix
163       systems.
164
165       YYYY-MM-DDThh:mm:ss
166
167       The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the
168       time format to be hh:mm:ss (24 hour clock), and if combined, they
169       should be concatenated with date first and with a capital 'T' in front
170       of the time.
171
172       Week Number
173
174       The week number may be an unknown concept to some readers.  The ISO
175       8601 standard defines that weeks begin on a Monday and week 1 of the
176       year is the week that includes both January 4th and the first Thursday
177       of the year.  In other words, if the first Monday of January is the
178       2nd, 3rd, or 4th, the preceding days of the January are part of the
179       last week of the preceding year.  Week numbers range from 1 to 53.
180
181       Global Overriding
182
183       Finally, it's possible to override localtime and gmtime everywhere, by
184       including the ':override' tag in the import list:
185
186           use Time::Piece ':override';
187

AUTHOR

189       Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while
190       creating Time::Piece for core perl)
191

License

193       This module is free software, you may distribute it under the same
194       terms as Perl.
195

BUGS

201       The test harness leaves much to be desired. Patches welcome.
202
203
204
205perl v5.8.8                       2005-11-15                          Piece(3)