ext/Time/Piece/README

   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