view release on metacpan or  search on metacpan

lib/DateTime/Precise.pm  view on Meta::CPAN

 $t1->set_localtime_from_epoch_time;
 $t1->set_gmtime_from_epoch_time(time + 120.987);
 $t1->set_from_datetime('1998.03.23 16:58:14.65');
 $t1->set_time('YDHMS', 1998, 177, 9, 15, 26.5);

 # This is the same as $d3->set_from_datetime(...)
 $t3->dscanf("%^Y.%M.%D %h:%m:%s", "1998.03.25 20:25:23");
 if ($msg = $d1->dscanf("%~M", $input)) {
     print "error: $msg\n";
     print "Must enter a three-letter month abbrev.\n";
 }

 # Get different parts of the time.
 $year    = $t3->year;
 $month   = $t3->month;
 $day     = $t3->day;
 $hours   = $t3->hours;
 $minutes = $t3->minutes;
 $seconds = $t3->seconds;
 ($year, $day_of_year) = $t3->get_time('Yj');

 # Print times and dates.
 print $t2->asctime;
 print $t2->strftime('%T %C%n');
 print $t2->dprintf("%^Y.%M.%D %h:%m:%s");           # datetime
 print $t2->dprintf("%~w %~M %-D %h:%m:%s CST %^Y"); # ctime

 # Copy times.
 my $t4 = $t2->copy;

 # Set one time object to the same time as another: set $t3 equal to $t2.
 $t3->clone($t2);

 # Find the difference between two times.
 $secs_from_midnight = $t4 - $t1;
 $secs_from_midnight = $t4->diff($t1);

 # Add seconds, days, months, etc to time.
 $t1 = $t4 + 3600;                      # $t1 is now an hour after midnight
 $t1->inc_month(2);                     # add two months to $t1
 $t1->floor_month;                      # set $t1 to the first of the month
 $t1 -= 0.25;                           # subtract 1/4 of a second from $t1

 # Can compare and sort DateTime::Precise.
 print "It's late!!!" if ($t1 > $t4);
 @sorted = sort @birthdays;             # normal comparisons work fine

 # Get the GPS weeks, seconds and day.
 $gps_week    = $t1->gps_week;
 $gps_seconds = $t1->gps_seconds;
 $gps_day     = $t1->gps_day;
 ($gps_week, $gps_seconds, $gps_day) = $t1->gps_week_seconds_day;

=head1 DESCRIPTION

The purpose of this library was to replace our dependence on Unix
epoch time, which, being limited to a range of about 1970 to 2030, is
inadequate for our purposes (we have data as old as 1870).  This date
library effectively handles dates from A.D. 1000 to infinity, and
would probably work all the way back to 0 (ignoring, of course, the
switch-over to the Gregorian calendar).  The useful features of Unix
epoch time (ease of date difference calculation and date comparison,
strict ordering) are preserved, and elements such as human-legibility
are added.  The library handles fractional seconds and some date/time
manipulations used for the Global Positioning Satellite system.

The operators +/-, <=>, cmp, stringify are overloaded.  Addition
handles seconds and fractions of seconds, subtraction handles seconds
or date differences, compares work, and stringification returns the a
representation of the date.

The US Geological Survey (USGS) likes midnight to be 24:00:00 of the
previous day, not 00:00:00 of the day people expect.  If
$DateTime::Precise::USGSMidnight is set, dprintf will always print
midnight as 24:00:00 and the date returned from dprintf will have the
previous day's date.  Regardless, time is always stored internally as
00:00:00.

=head1 CONSTRUCTOR

=over 4

=item B<new>

=item B<new>('1998. 4. 3 12:13:44')

=item B<new>(time() - 100.23456)

=item B<new>('YDHMS', 1998, 200, 13, 16, 49.5)

This creates a new time object.  If no argument is passed, then the
time object is initialized with the time returned from I<gmtime>
(I<time>()).  The second form is used to set the time explicitly.  The
argument can be in one of three formats: "YYYY.MM.DD hh:mm:ss.ffff",
"YYYY.MM.DD" (midnight assumed), or "YYYYMMDDhhmmss.ffff".  Here ffff
are the fractions of seconds.  The third form sets the time using
I<gmtime>() with fractional seconds allowed.  The fourth form sets the
time using a format as the first argument followed by the particular
date adjustments as the following arguments.  See set_time() for more
information.  If the new fails, then new returns an empty list in a
list context, an undefined value in a scalar context, or nothing in a
void context.

Because the second and third forms pass only one argument to new(),
there must be a way of distinguishing them.  Currently the following
test is used: if any non-digit characters are found in the argument or
if the string form of the argument is longer than 10 character, then
assume it to be a string to parse for the date.  Otherwise it is the
time since the Unix epoch.  The string length of 10 was chosen since
when the Unix epoch time flips to 11 digits, it'll be roughly year
2287.

=back 4

=head1 METHODS

=over 4

=item B<set_from_datetime> I<datetime>

Set date/time from passed date/time string "YYYY.MM.DD hh:mm:ss.fff".