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