NAME

DMA::ISODate.pm - ISO date handling.

SYNOPSIS

use DMA::ISODate;

$obj         = DMA::ISOdate->new ($datestring);
$obj         = DMA::ISOdate->now;
$obj         = DMA::ISOdate->utc;
$obj         = DMA::ISOdate->unix ($time, $gmflag);
$obj         = DMA::ISOdate->new_formatted ($fmt, $string);

$datestring  = $obj->get;
$datestring  = $obj->canonical;
$obj         = $obj->yearly;
$obj         = $obj->monthly;
$obj         = $obj->isyearly;
$obj         = $obj->ismonthly;
$quarter     = $obj->quarter;
$season      = $obj->season;
$datestring  = $obj->date;
$timestring  = $obj->time;
$havetime    = $obj->havetime;
$y2k         = $obj->y2k;
$utc         = $obj->isUTC;

($yr,$mon,$day,$hr,$min,$sec,$havetime,$utc,$y2k) = $obj->timearray;

Inheritance

UNIVERSAL

Description

The primary date time we use is the ISO date, almost always in the basic form of YYYYMMDD , like 20021209, but the DMA::ISOdate class will attempt to create an ISODate from what ever you give it:

Input data               Canonical ISO result
YYMMDD              =>       19YYMMDD000000
YYYMMDD             => (1900+YYY)MMDD000000
YYYYMMDD            =>       YYYYMMDD000000
YYYYYMMDD           =>      YYYYYMMDD000000
YYYYYYMMDD          =>     YYYYYYMMDD000000
YYYYYYYMMDD         =>    YYYYYYYMMDD000000
YYMMDDHHMMSS        =>       19YYMMDDHHMMSS
YYYMMDDHHMMSS       =>  (1900+YY)MMDDHHMMSS
YYYYMMDDHHMMSS      =>       YYYYMMDDHHMMSS
{Y..}YYYYMMDDHHMMSS =>  {Y..}YYYYMMDDHHMMSS    

Note that a minimum of 4 digits is needed to correctly express years like 40AD so as to differentiate it from 1940AD which is what the Y2K correction would do with "401209". There are also problems: years cannot be expressed beyond 9999999 in the date only format.

Two digit years (00-99) are assume to be Y2K legacy dates. We set the y2k flag and add 1900 to the year value when we see one.

Three digit years (000-999) are likely to be uncorrected Unix date returns. We do not set the y2k but we do add 1900. This is safe until we hit what I'll call the "U2K" date of 2038 when Unix 32b int timevals roll over. This is not a problem for this Class; we follow the philosophy of "be liberal on inputs and conservative on outputs".

If this all seems very ad hoc -- it is. Date formats are very ad hoc with ambiguities which can only be decided with contextual information. That's a job for people, not a poor wee ISODate Class.

Four digit year formats are not limited to 4 digits. We can express dates far into the future. In any place hereafter where we use "YYYY", any number of extra digits are possible.

[We aren't affected by the size of Unix timval (ie the 2038 max year) except it is not convenient right now to do a perpetual calendar of my own to check the validity of a date.]

We do not, however, have any means of representing dates BC. For this we might consider using the Peter Kokh dating system which adds 10000 to the AD date to represent all of human history after the end of the most recent Ice Age. This allows much easier translation between all modern and ancient dating systems if you remember there was no year zero as they had not gotten around to inventing nothing back then. (Given some recent discoveries offshore in India, I might prefer adding 20000 years!)

Examples

None.

Class Variables

None.

Instance Variables

y2k            Set if external input was in two digit year format, t/f.
havetime       Set if input included the time, t/f
isUTC          date/time is known to be UTC, t/f. 
               (What should the default be since we will
                only know this if we got the time via newgm.)
date           "YYYYMMDD" 
time           "HHMMSS", default is "000000"
yr             integer year, 0 -size of int
mon            integer month, 1-12,; 0=no month
day            integer day, 1-28,29,30 or 31; 0=no day
hr             integer hour, 0-23
min            integer minute, 0-59
sec            integer second, 0-59

Class Methods

$obj = DMA::ISOdate->new ($datestring)

Assume the $datestring is a local ISO date or date/time in one of the formats discussed earlier. Returns undef if $datestring can't be parsed our way; 1900 is added to the year if 2 or 3 digits are found and the y2k flag set for 2 digit years. havetime is set if there was an HHMMSS in the string.

Returns a new object or undef on failure.

$obj = DMA::ISOdate->new_formatted ($fmt, $string)

Use a Perl date format string to identify the date format we believe $string to be in. It returns undef instead of creating a new object if the date doesn't work in the given format.

$obj = DMA::ISOdate->now

Create an object with the current time set to right now in local time. Always succeeds, always Y2K compliant and has HHMMSS available.

$obj = DMA::ISOdate->unix ($time, $gmflag)

Create an object for a unix timeval. $time is required and assumed to be a unix time integer. If $gmflag is present and set, make it a UTC time, otherwise it is local time. Always succeeds, always Y2K compliant and has HHMMSS available.

This routine is useful when dealing with info from archive file directory stats.

$obj = DMA::ISOdate->utc

Create an object with the current time set to right now in UTC time. Always succeeds, always Y2K compliant and has HHMMSS available.

Instance Methods

$datestring = $obj->canonical

Returns an the object's ISODATE. In a canonical form: YYYYMMDD HHMMSS . If havetime is not set, we get YYYYMMDD000000.

$datestring = $obj->date

Returns the ISO date as YYYYMMDD .

$datestring = $obj->get

Returns an the object's ISODATE. In one of two forms, either YYYYMMDD if havetime is not set or YYYYMMDDHHMMSS if it is.

$havetime = $obj->havetime

True if we have a time of day stored.

$obj = $obj->ismonthly

Test if the ISO date is suitable for things like monthly magazines. Returns true if havetime and day of month are clear. It means your ISO date is of the form "19950500".

$utc = $obj->isUTC

True if the time we stored was UTC.

$obj = $obj->isyearly

Test if the ISO date is suitable for things like yearly reports. Returns true if havetime, month and day of month are clear. It means your ISO date is of the form "19950000".

$obj = $obj->monthly

Change the ISO date so it is of use for things like monthly magazines. havetime is cleared. All time and date field below month are zeroed. Your ISO date will now look like "19950500".

$quarter = $obj->quarter

Returns the quarter string for the date. Q1,Q2,Q3,Q4 or Q1-Q4 if the date has no month, eg "19950000".

$season = $obj->season

Returns the season: winter, spring,summer,fall.

$timestring = $obj->time

Returns the time as HHMMSS if havetime is set; otherwise the midnight time string "000000".

($yr,$mon,$day,$hr,$min,$sec,$havetime,$utc,$y2k) = $obj->timearray

Return the date/time information.

$y2k = $obj->y2k

True if we applied a Y2K correction to the year in our stored date.

$obj = $obj->yearly

Change the ISO date so it is of use for things like yearly reports. havetime is cleared. All time and date field below year are zeroed. Your ISO date will now look like "19950000".

Private Class Methods

$obj = DMA::ISOdate->_new ($type,$gmflag,$datestring)

Internal base initializer method which all the other initializer methods call.

Not part of the advertised interface for this class, so don't try to use it directly.

Returns self or undef if no date found/created.

Private Instance Methods

None, although I may wish to include the code comments from _isodate here as it is quite extensive.

KNOWN BUGS

See TODO.

SEE ALSO

None.

AUTHOR

Dale Amon <amon@vnl.com>

cpanm DMA::FSM

perl -MCPAN -e shell
install DMA::FSM