README
1NAME
2 Time::Object - Object Oriented time objects
3
4SYNOPSIS
5 use Time::Object;
6
7 my $t = localtime;
8 print "Time is $t\n";
9 print "Year is ", $t->year, "\n";
10
11DESCRIPTION
12 This module replaces the standard localtime and gmtime functions with
13 implementations that return objects. It does so in a backwards
14 compatible manner, so that using localtime/gmtime in the way documented
15 in perlfunc will still return what you expect.
16
17 The module actually implements most of an interface described by Larry
18 Wall on the perl5-porters mailing list here:
19 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.
20 html
21
22USAGE
23 After importing this module, when you use localtime or gmtime in a
24 scalar context, rather than getting an ordinary scalar string
25 representing the date and time, you get a Time::Object object, whose
26 stringification happens to produce the same effect as the localtime and
27 gmtime functions. There is also a new() constructor provided, which is
28 the same as localtime(), except when passed a Time::Object object, in
29 which case it's a copy constructor. The following methods are available
30 on the object:
31
32 $t->sec # also available as $t->second
33 $t->min # also available as $t->minute
34 $t->hour # 24 hour
35 $t->mday # also available as $t->day_of_month
36 $t->mon # 1 = January
37 $t->_mon # 0 = January
38 $t->monname # February
39 $t->month # same as $t->monname
40 $t->year # based at 0 (year 0 AD is, of course 1 BC)
41 $t->_year # year minus 1900
42 $t->yy # 2 digit year
43 $t->wday # 1 = Sunday
44 $t->_wday # 0 = Sunday
45 $t->day_of_week # 0 = Sunday
46 $t->wdayname # Tuesday
47 $t->day # same as wdayname
48 $t->yday # also available as $t->day_of_year, 0 = Jan 01
49 $t->isdst # also available as $t->daylight_savings
50
51 $t->hms # 12:34:56
52 $t->hms(".") # 12.34.56
53 $t->time # same as $t->hms
54
55 $t->ymd # 2000-02-29
56 $t->date # same as $t->ymd
57 $t->mdy # 02-29-2000
58 $t->mdy("/") # 02/29/2000
59 $t->dmy # 29-02-2000
60 $t->dmy(".") # 29.02.2000
61 $t->datetime # 2000-02-29T12:34:56 (ISO 8601)
62 $t->cdate # Tue Feb 29 12:34:56 2000
63 "$t" # same as $t->cdate
64
65 $t->epoch # seconds since the epoch
66 $t->tzoffset # timezone offset in a Time::Seconds object
67
68 $t->julian_day # number of days since Julian period began
69 $t->mjd # modified Julian day
70
71 $t->week # week number (ISO 8601)
72
73 $t->is_leap_year # true if it its
74 $t->month_last_day # 28-31
75
76 $t->time_separator($s) # set the default separator (default ":")
77 $t->date_separator($s) # set the default separator (default "-")
78 $t->day_list(@days) # set the default weekdays
79 $t->mon_list(@days) # set the default months
80
81 $t->strftime(FORMAT) # same as POSIX::strftime (without the overhead
82 # of the full POSIX extension)
83 $t->strftime() # "Tue, 29 Feb 2000 12:34:56 GMT"
84
85 Local Locales
86
87 Both wdayname (day) and monname (month) allow passing in a list to use
88 to index the name of the days against. This can be useful if you need to
89 implement some form of localisation without actually installing or using
90 locales.
91
92 my @days = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
93
94 my $french_day = localtime->day(@days);
95
96 These settings can be overriden globally too:
97
98 Time::Piece::day_list(@days);
99
100 Or for months:
101
102 Time::Piece::mon_list(@months);
103
104 And locally for months:
105
106 print localtime->month(@months);
107
108 Date Calculations
109
110 It's possible to use simple addition and subtraction of objects:
111
112 use Time::Seconds;
113
114 my $seconds = $t1 - $t2;
115 $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)
116
117 The following are valid ($t1 and $t2 are Time::Object objects):
118
119 $t1 - $t2; # returns Time::Seconds object
120 $t1 - 42; # returns Time::Object object
121 $t1 + 533; # returns Time::Object object
122
123 However adding a Time::Object object to another Time::Object object will
124 cause a runtime error.
125
126 Note that the first of the above returns a Time::Seconds object, so
127 while examining the object will print the number of seconds (because of
128 the overloading), you can also get the number of minutes, hours, days,
129 weeks and years in that delta, using the Time::Seconds API.
130
131 Date Comparisons
132
133 Date comparisons are also possible, using the full suite of "<", ">",
134 "<=", ">=", "<=>", "==" and "!=".
135
136 YYYY-MM-DDThh:mm:ss
137
138 The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the
139 time format to be hh:mm:ss (24 hour clock), and if combined, they should
140 be concatenated with date first and with a capital 'T' in front of the
141 time.
142
143 Week Number
144
145 The *week number* may be an unknown concept to some readers. The ISO
146 8601 standard defines that weeks begin on a Monday and week 1 of the
147 year is the week that includes both January 4th and the first Thursday
148 of the year. In other words, if the first Monday of January is the 2nd,
149 3rd, or 4th, the preceding days of the January are part of the last week
150 of the preceding year. Week numbers range from 1 to 53.
151
152 Global Overriding
153
154 Finally, it's possible to override localtime and gmtime everywhere, by
155 including the ':override' tag in the import list:
156
157 use Time::Object ':override';
158
159AUTHOR
160 Matt Sergeant, matt@sergeant.org Jarkko Hietaniemi, jhi@iki.fi (while
161 creating Time::Piece for core perl)
162
163License
164 This module is free software, you may distribute it under the same terms
165 as Perl.
166
167SEE ALSO
168 The excellent Calendar FAQ at
169 http://www.tondering.dk/claus/calendar.html
170
171BUGS
172 The test harness leaves much to be desired. Patches welcome.
173
174