 382C8tQ - Time::Fields.pm created by Pip@CPAN.org as an abstract base 
   class for more specialized Time objects (Time::Frame && Time::PT).
 Notz: 
   timelocal($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
   Unix epoch 1970-2036 or something
   PT   epoch 1361-2631
   potential smaller fields:
       kink as 60th-of-a-jink? tink as 60th-of-a-kink? ... X as 60th-of-a-Y
     frame 0.0166666666666667        CYMDhmsfjktbpaz
     jink  0.000277777777777778               0.3 milliseconds (thousanths)
     kink  0.00000462962962962963             5   microseconds (millionths)
     tink  0.0000000771604938271605          77   nano seconds (billionths)
     blip  0.00000000128600823045267          1   nano second 
       RealTimeOperatingSystems may need micro or nano second precision
     pip   0.0000000000214334705075446       21   pico seconds (trillionths)
     ax    0.000000000000357224508459076      0.4 pico seconds
           0.00000000000000595374180765127    6   femtoseconds (10e-15)
           0.0000000000000000992290301275212 99   atto seconds (10e-18)
           0.00000000000000000165381716879202 2   atto seconds
           0.000000000000000000027563619479867            27   zepto   -21
           0.000000000000000000000459393657997783          0.5 zepto
           0.00000000000000000000000765656096662972        8   yocto   -24
           0.000000000000000000000000127609349443829       0.1 yocto
           0.00000000000000000000000000212682249073048     2   harpo   -27
           0.0000000000000000000000000000354470415121746  35   groucho -30
           0.000000000000000000000000000000590784025202911 0.6 groucho
      zepto (10e-21) yocto (10e-24) harpo (10e-27) groucho (10e-30) 
      zeppo (10e-33) gummo (10e-36) chico (10e-39)

NAME

  Time::Fields - abstract objects to store distinct time fields

VERSION

  This documention refers to version 1.0.3CBIQHM of 
    Time::Fields, which was released on Thu Dec 11 18:26:17:22 2003.

SYNOPSIS

    package Time::Fields::NewChildPackageOfTimeFields;
    use base qw(Time::Fields);
    
    # NewChildPackageOfTimeFields definition...

DESCRIPTION

  Time::Fields defines simple time objects with distinct fields for:
      Century, Year, Month, Day, hour, minute, second, frame, jink, zone
    along with methods to manipulate those fields && modify their
    default presentation.  Normally, a frame is one 60th-of-a-
    second && a jink is one 60th-of-a-frame or about 0.3 milliseconds.
    The plural for 'jink' is 'jinx'.  Fields data && methods are 
    meant to be inherited by other classes (namely Time::Frame && 
    Time::PT) which implement specific useful interpretations of 
    individual Time::Fields.

2DO

  use_? filters should get auto-set when non-used fields get assigned
  mv Simp, HTML, ANSI color options && code data into Fields && remove
    redundancy from Frame && PT
        What else does Fields need?

WHY?

  The reason I created Fields was that I have grown so enamored with
    Bass64 representations of everything around me that I was 
    compelled to write a simple clock utility ( `pt` ) using Bass64.
    This demonstrated the benefit to be gained from time objects with
    distinct fields && configurable precision.  Thus, Time::Fields
    was written to be the abstract base class for:
      Time::Frame  ( creates objects which represent spans    of time )
          && 
      Time::PT     ( creates objects which represent instants in time )

USAGE

  Many of Time::Fields's methods have been patterned after the 
    excellent Time::Piece module written by Matt Sergeant 
    <matt@sergeant.org> && Jarkko Hietaniemi <jhi@iki.fi>.

  new(<InitType>, <InitData>) - Time::Fields's constructor can be 
    called as a class method to create a brand new object or as
    an object method to copy an existing object.  Beyond that,
    new() can initialize Fields objects 3 different ways:
     -1) <packedB64InitStringImplies'str'>
        eg. Time::Fields->new('0123456789');
      0) 'str'  => <packedB64InitString>
        eg. Time::Fields->new('str'  => '0123456789');
      1) 'list' => <arrayRef>
        eg. Time::Fields->new('list' => [0, 1, 2..9]);
      2) 'hash' => <hashRef>
        eg. Time::Fields->new('hash' => {'jink' => 8, 'year' => 2003})
    *Note*  If only a valid 'str'-type parameter is given to new 
      (but no accompanying initialization value), the parameter 
      is interpreted as an implied 'str' value.
        eg. Time::Fields->new('0123456789');
      This implied 'str'-type initialization will probably be
        the most common Time::Fields object creation mechanism
        when individual fields do not exceed 64 since this 
        efficient representation is why the module was created.

  The following methods allow access to individual fields of 
    existent Time::Fields objects:

    $t->C  or  $t->century
    $t->Y  or  $t->year
    $t->M  or  $t->month
    $t->D  or  $t->day
    $t->h  or  $t->hour
    $t->m  or  $t->minute
    $t->s  or  $t->second
    $t->f  or  $t->frame
    $t->j  or  $t->jink
    $t->z  or  $t->zone

  Any combination of above single letters can be used as well.  
    Following are some common useful examples:
  
    $t->hms                 # returns list of fields eg. [12, 34, 56]
    $t->hms(12, 56, 34)     # sets fields: h = 12, m = 56, s = 34
    $t->hmsf                # [12, 34, 56, 12]
    $t->hmsfj               # [12, 34, 56, 12, 34]
    $t->hmsfjz              # [12, 34, 56, 12, 34, 16]
    $t->time                # same as $t->hms
    $t->alltime             # same as $t->hmsfjz
    $t->YMD                 # [2000,  2,   29]
    $t->MDY                 # [   2, 29, 2000]
    $t->DMY                 # [  29,  2, 2000]
    $t->CYMD                # [  20,  0,    2, 29]
    $t->date                # same as $t->YMD
    $t->alldate             # same as $t->CYMD
    $t->CYMDhmsfjz          # [  20,  0,    2, 29, 12, 13, 56, 12, 13, 16]
    $t->dt                  # same as $t->CYMDhmsfjz
    $t->all                 # same as $t->CYMDhmsfjz
    "$t"                    # same as $t->CYMDhmsfjz

  Method names can be in any case with the following exceptions.  
    Special handling exists to resolve ambiguity between the Month && 
    minute fields.  If a lowercase 'm' is used adjacent to a 'y' or 'd'
    of either case, it is interpreted as Month.  Otherwise, the case of 
    the 'm' distinguishes Month from minute.  An uppercase 'M' is ALWAYS
    Month.  An adjacent uppercase 'H' or 'S' will not turn an uppercase
    'M' into minute.  Method names which need to specify Month or minute
    fields can also optionally specify the distinguishing vowel 
    ('o' or 'i') instead of 'M' or 'm'.

    $t->ymd                 # same as $t->YMD
    $t->dmy                 # same as $t->DMY
    $t->MmMm                # Month minute Month minute
    $t->HMS                 # hour Month second! NOT same as $t->hms 
    $t->yod                 # same as $t->YMD
    $t->chmod               # Century hour minute Month Day
    $t->FooIsMyJoy          # frame Month Month     minute second
                            #      Month Year     jink Month Year

NOTES

  Whenever individual Time::Fields attributes are going to be 
    printed or an entire object can be printed with multi-colors,
    the following mapping should be employed whenever possible:
           D      Century -> DarkRed
           A      Year    -> Red
           T      Month   -> Orange
           E      Day     -> Yellow
                   hour   -> Green
            t      minute -> Cyan
            i      second -> Blue
            m      frame  -> Purple
            e      jink   -> DarkPurple
                   zone   -> Grey or White

  Even though Time::Fields is designed to be an abstract base class,
    it has not been written to croak on direct usage && object 
    instantiation because simple Fields objects may already be
    worthwhile.

  I hope you find Time::Fields useful.  Please feel free to e-mail
    me any suggestions || coding tips || notes of appreciation 
    ("app-ree-see-ay-shun").  Thank you.  TTFN.

CHANGES

  Revision history for Perl extension Time::Fields:

- 1.0.3CBIQHM  Thu Dec 11 18:26:17:22 2003

  * 

- 1.0.3CB7Qb0  Thu Dec 11 07:26:37:00 2003

  * updated pod && prepared for release

- 1.0.3CA8oiI  Wed Dec 10 08:50:44:18 2003

  * overloaded for stringification, implemented use methods, &&
      cleaned up documentation

- 1.0.39GHeCl  Tue Sep 16 17:40:12:47 2003

  * incorporated stuff learned from ObjectOrientedPerl (Conway)

- 1.0.382DLbX  Sat Aug  2 13:21:37:33 2003

  * fleshed out documentation && ideas

- 1.0.37VG26k  Thu Jul 31 16:02:06:46 2003

  * original version

INSTALL

  Please run:
        `perl -MCPAN -e "install Time::Fields"`
    or uncompress the package && run the standard:
        `perl Makefile.PL; make; make test; make install`

FILES

  Time::Fields requires:
    Carp                to allow errors to croak() from calling sub
    Math::BaseCnv       to handle number-bass conversion
  Time::Fields utilizes (if available):
    Time::HiRes         to provide sub-second time precision
    Time::Local         to provide Unix time conversion options

SEE ALSO

  Time::Frame && Time::PT

LICENSE

  Most source code should be Free!
    Code I have lawful authority over is && shall be!
  Copyright: (c) 2003, Pip Stuart.  All rights reserved.
  Copyleft :  I license this software under the GNU General Public
    License (version 2).  Please consult the Free Software Foundation
    (http://www.fsf.org) for important information about your freedom.

AUTHOR

  Pip Stuart <Pip@CPAN.org>

