view release on metacpan or  search on metacpan

lib/DMA/ISODate.pm  view on Meta::CPAN

 $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;

=head1 Inheritance

 UNIVERSAL

=head1 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!)

=head1 Examples

 None.

=head1 Class Variables

 None.

=head1 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

=head1 Class Methods

=over 4

=item B<$obj = DMA::ISOdate-E<gt>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.

=item B<$obj = DMA::ISOdate-E<gt>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.

=item B<$obj = DMA::ISOdate-E<gt>now>

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

=item B<$obj = DMA::ISOdate-E<gt>unix ($time, $gmflag)>