Commit | Line | Data |
302d38aa |
1 | NAME |
2 | Time::Object - Object Oriented time objects |
3 | |
4 | SYNOPSIS |
5 | use Time::Object; |
6 | |
7 | my $t = localtime; |
8 | print "Time is $t\n"; |
9 | print "Year is ", $t->year, "\n"; |
10 | |
11 | DESCRIPTION |
12 | This module replaces the standard localtime and gmtime functions |
13 | with implementations that return objects. It does so in a |
14 | backwards compatible manner, so that using localtime/gmtime in |
15 | the way documented in perlfunc will still return what you |
16 | expect. |
17 | |
18 | The module actually implements most of an interface described by |
19 | Larry Wall on the perl5-porters mailing list here: |
20 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000- |
21 | 01/msg00241.html |
22 | |
23 | USAGE |
24 | After importing this module, when you use localtime or gmtime in |
25 | a scalar context, rather than getting an ordinary scalar string |
26 | representing the date and time, you get a Time::Object object, |
27 | whose stringification happens to produce the same effect as the |
28 | localtime and gmtime functions. There is also a new() |
29 | constructor provided, which is the same as localtime(), except |
30 | when passed a Time::Object object, in which case it's a copy |
31 | constructor. The following methods are available on the object: |
32 | |
33 | $t->sec # also available as $t->second |
34 | $t->min # also available as $t->minute |
35 | $t->hour |
36 | $t->mday # also available as $t->day_of_month |
37 | $t->mon # based at 1 |
38 | $t->_mon # based at 0 |
39 | $t->monname # February |
40 | $t->month # same as $t->monname |
41 | $t->year # based at 0 (year 0 AD is, of course 1 BC). |
42 | $t->_year # year minus 1900 |
43 | $t->yr # 2 digit year |
44 | $t->wday # based at 1 = Sunday |
45 | $t->_wday # based at 0 = Sunday |
46 | $t->day_of_week # based at 0 = Sunday |
47 | $t->wdayname # Tuesday |
48 | $t->day # same as wdayname |
49 | $t->yday # also available as $t->day_of_year |
50 | $t->isdst # also available as $t->daylight_savings |
51 | $t->hms # 01:23:45 |
52 | $t->ymd # 2000/02/29 |
53 | $t->mdy # 02/29/2000 |
54 | $t->dmy # 29/02/2000 |
55 | $t->date # Tue Feb 29 01:23:45 2000 |
56 | "$t" # same as $t->date |
57 | $t->epoch # seconds since the epoch |
58 | $t->tzoffset # timezone offset in a Time::Seconds object |
59 | $t->strftime(FORMAT) # same as POSIX::strftime (without POSIX.pm) |
60 | |
61 | Date Calculations |
62 | |
63 | It's possible to use simple addition and subtraction of objects: |
64 | |
65 | use Time::Seconds; |
66 | |
67 | my $seconds = $t1 - $t2; |
68 | $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds) |
69 | |
70 | The following are valid ($t1 and $t2 are Time::Object objects): |
71 | |
72 | $t1 - $t2; # returns Time::Seconds object |
73 | $t1 - 42; # returns Time::Object object |
74 | $t1 + 533; # returns Time::Object object |
75 | |
76 | However adding a Time::Object object to another Time::Object |
77 | object will cause a runtime error. |
78 | |
79 | Note that the first of the above returns a Time::Seconds object, |
80 | so while examining the object will print the number of seconds |
81 | (because of the overloading), you can also get the number of |
82 | minutes, hours, days, weeks and years in that delta, using the |
83 | Time::Seconds API. |
84 | |
85 | Date Comparisons |
86 | |
87 | Date comparisons are also possible, using the full suite of "<", |
88 | ">", "<=", ">=", "<=>", "==" and "!=". |
89 | |
90 | Global Overriding |
91 | |
92 | Finally, it's possible to override localtime and gmtime |
93 | everywhere, by including the 'overrideGlobally' tag in the |
94 | import list: |
95 | |
96 | use Time::Object 'overrideGlobally'; |
97 | |
98 | I'm not too keen on this name yet - suggestions welcome... |
99 | |
100 | AUTHOR |
101 | Matt Sergeant, matt@sergeant.org |
102 | |
103 | License |
104 | |
105 | This module is free software, you may distribute it under the |
106 | same terms as Perl. |
107 | |
108 | Bugs |
109 | |
110 | The test harness leaves much to be desired. Patches welcome. |
111 | |