/ 
Time-PT-1.2.565EHOV
River stage zero No dependents
/ Time::Fields

NAME

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

VERSION

This documentation refers to version 1.2.565EHOV of Time::Fields, which was released on Sun Jun 5 14:17:24:31 2005.

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 unused fields get assigned
- What else does Fields need?

WHY?

The reason I created Fields was that I have grown so enamored with Base64 representations of everything around me that I was compelled to write a simple clock utility ( `pt` ) using Base64. 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 the following ways:

* <packedB64InitStringImplies'str'>
  eg. Time::Fields->new('0123456789');
* 'str'  => <packedB64InitString>
  eg. Time::Fields->new('str'  => '0123456789');
* 'list' => <arrayRef>
  eg. Time::Fields->new('list' => [0, 1, 2..9]);
* 'hash' => <hashRef>
  eg. Time::Fields->new('hash' => {'jink' => 8, 'year' => 2003})

b<*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

Month / minute Exceptions

Fields object 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 be uniquely specified by their 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.2.565EHOV Sun Jun 5 14:17:24:31 2005

* combined Fields, Frame, && PT into one pkg (so see PT CHANGES section for updates to Fields or Frame)

- 1.0.3CCA4Eh Fri Dec 12 10:04:14:43 2003

* removed indenting from POD NAME field

- 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

* cleaned up documentation

* implemented use methods

* overloaded for stringification

- 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::PT"`

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-base 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-2004, Pip Stuart. Copyleft : This software is licensed under the GNU General Public License (version 2), && as such comes with NO WARRANTY. Please consult the Free Software Foundation (http://FSF.Org) for important information about your freedom.

AUTHOR

Pip Stuart <Pip@CPAN.Org>