1DateTime::Precise(3)  User Contributed Perl Documentation DateTime::Precise(3)
2
3
4

NAME

6       DateTime::Precise - Perform common time and date operations with
7       additional GPS operations
8

SYNOPSIS

10        use DateTime::Precise;
11
12        use DateTime::Precise qw(:TimeVars);
13
14        # Constructors and ways to set time.
15        $t1 = DateTime::Precise->new;
16        $t2 = DateTime::Precise->new('1998. 4. 3 12:13:44.054');
17        $t3 = DateTime::Precise->new(time() - 100.23456);
18        $t4 = DateTime::Precise->new('1998.04.24');
19        $t1->set_localtime_from_epoch_time;
20        $t1->set_gmtime_from_epoch_time(time + 120.987);
21        $t1->set_from_datetime('1998.03.23 16:58:14.65');
22        $t1->set_time('YDHMS', 1998, 177, 9, 15, 26.5);
23
24        # This is the same as $d3->set_from_datetime(...)
25        $t3->dscanf("%^Y.%M.%D %h:%m:%s", "1998.03.25 20:25:23");
26        if ($msg = $d1->dscanf("%~M", $input)) {
27            print "error: $msg\n";
28            print "Must enter a three-letter month abbrev.\n";
29        }
30
31        # Get different parts of the time.
32        $year    = $t3->year;
33        $month   = $t3->month;
34        $day     = $t3->day;
35        $hours   = $t3->hours;
36        $minutes = $t3->minutes;
37        $seconds = $t3->seconds;
38        ($year, $day_of_year) = $t3->get_time('Yj');
39
40        # Print times and dates.
41        print $t2->asctime;
42        print $t2->strftime('%T %C%n');
43        print $t2->dprintf("%^Y.%M.%D %h:%m:%s");           # datetime
44        print $t2->dprintf("%~w %~M %-D %h:%m:%s CST %^Y"); # ctime
45
46        # Copy times.
47        my $t4 = $t2->copy;
48
49        # Set one time object to the same time as another: set $t3 equal to $t2.
50        $t3->clone($t2);
51
52        # Find the difference between two times.
53        $secs_from_midnight = $t4 - $t1;
54        $secs_from_midnight = $t4->diff($t1);
55
56        # Add seconds, days, months, etc to time.
57        $t1 = $t4 + 3600;                      # $t1 is now an hour after midnight
58        $t1->inc_month(2);                     # add two months to $t1
59        $t1->floor_month;                      # set $t1 to the first of the month
60        $t1 -= 0.25;                           # subtract 1/4 of a second from $t1
61
62        # Can compare and sort DateTime::Precise.
63        print "It's late!!!" if ($t1 > $t4);
64        @sorted = sort @birthdays;             # normal comparisons work fine
65
66        # Get the GPS weeks, seconds and day.
67        $gps_week    = $t1->gps_week;
68        $gps_seconds = $t1->gps_seconds;
69        $gps_day     = $t1->gps_day;
70        ($gps_week, $gps_seconds, $gps_day) = $t1->gps_week_seconds_day;
71

DESCRIPTION

73       The purpose of this library was to replace our dependence on Unix epoch
74       time, which, being limited to a range of about 1970 to 2030, is
75       inadequate for our purposes (we have data as old as 1870).  This date
76       library effectively handles dates from A.D. 1000 to infinity, and would
77       probably work all the way back to 0 (ignoring, of course, the switch-
78       over to the Gregorian calendar).  The useful features of Unix epoch
79       time (ease of date difference calculation and date comparison, strict
80       ordering) are preserved, and elements such as human-legibility are
81       added.  The library handles fractional seconds and some date/time
82       manipulations used for the Global Positioning Satellite system.
83
84       The operators +/-, <=>, cmp, stringify are overloaded.  Addition
85       handles seconds and fractions of seconds, subtraction handles seconds
86       or date differences, compares work, and stringification returns the a
87       representation of the date.
88
89       The US Geological Survey (USGS) likes midnight to be 24:00:00 of the
90       previous day, not 00:00:00 of the day people expect.  If
91       $DateTime::Precise::USGSMidnight is set, dprintf will always print
92       midnight as 24:00:00 and the date returned from dprintf will have the
93       previous day's date.  Regardless, time is always stored internally as
94       00:00:00.
95

CONSTRUCTOR

97       new
98       new('1998. 4. 3 12:13:44')
99       new(time() - 100.23456)
100       new('YDHMS', 1998, 200, 13, 16, 49.5)
101           This creates a new time object.  If no argument is passed, then the
102           time object is initialized with the time returned from gmtime
103           (time()).  The second form is used to set the time explicitly.  The
104           argument can be in one of three formats: "YYYY.MM.DD
105           hh:mm:ss.ffff", "YYYY.MM.DD" (midnight assumed), or
106           "YYYYMMDDhhmmss.ffff".  Here ffff are the fractions of seconds.
107           The third form sets the time using gmtime() with fractional seconds
108           allowed.  The fourth form sets the time using a format as the first
109           argument followed by the particular date adjustments as the
110           following arguments.  See set_time() for more information.  If the
111           new fails, then new returns an empty list in a list context, an
112           undefined value in a scalar context, or nothing in a void context.
113
114           Because the second and third forms pass only one argument to new(),
115           there must be a way of distinguishing them.  Currently the
116           following test is used: if any non-digit characters are found in
117           the argument or if the string form of the argument is longer than
118           10 character, then assume it to be a string to parse for the date.
119           Otherwise it is the time since the Unix epoch.  The string length
120           of 10 was chosen since when the Unix epoch time flips to 11 digits,
121           it'll be roughly year 2287.
122

METHODS

124       set_from_datetime datetime
125           Set date/time from passed date/time string "YYYY.MM.DD
126           hh:mm:ss.fff".  If set_from_datetime successfully parses datetime,
127           then the newly set date/time object is returned, otherwise it
128           returns an empty list in a list context, an undefined value in a
129           scalar context, or nothing in a void context.
130
131       set_localtime_from_epoch_time [epoch]
132           Set from epoch time into the local time zone.  If epoch is passed,
133           then use that time to set the current time, otherwise use the time
134           as returned from time() or from Time::HiRes::time() if the
135           Time::HiRes module can be loaded.  If the Time::HiRes::time() can
136           be imported, then the resulting loaded time most likely will
137           contain a fractional second component.  The newly set date/time
138           object is returned.  The epoch can contain fractional seconds.
139
140       set_gmtime_from_epoch_time [epoch]
141           Set from the epoch time into the standard Greenwich time zone.  If
142           epoch is passed, then use that time to set the current time,
143           otherwise use the time as returned from time() or from
144           Time::HiRes::time() if the Time::HiRes module can be loaded.  If
145           the Time::HiRes::time() can be imported, then the resulting loaded
146           time most likely will contain a fractional second component.  The
147           newly set date/time object is returned.  The epoch can contain
148           fractional seconds.
149
150       set_from_day_of_year year day_of_year
151           Set date/from from the year and the decimal day of the year.
152           Midnight January 1st is day 1, noon January 1st is 1.5, etc.  If
153           the date was successfully set, then the newly set date/time object
154           is returned, otherwise it returns an empty list in a list context,
155           an undefined value in a scalar context, or nothing in a void
156           context.
157
158       set_from_serial_day serial_day_number
159           Set the date/time from the serial day.  See also serial_day().  If
160           the date was successfully set, then the newly set date/time object
161           is returned, otherwise is returns an empty list in a list context,
162           an undefined value in a scalar context, or nothing in a void
163           context.
164
165       set_from_gps_week_seconds gps_week gps_seconds
166           Set the current time using the number of weeks and seconds into the
167           week since GPS epoch (January 6, 1980 UTC).  If the date was
168           successfully set, then the newly set date/time object is returned,
169           otherwise is returns an empty list in a list context, an undefined
170           value in a scalar context, or nothing in a void context.
171
172       set_time format [arg, [arg, ...]]
173           Set the time.  format is a string composed of a select set of
174           characters.  Some characters may take an optional argument, which
175           are listed following the format argument in the same order as the
176           characters.  The first character must be an absolute time:
177
178               N => Set time to now.  No argument taken.
179               G => Set time to GPS time 0 (January 6, 1980).  No argument taken.
180               Y => Set time to beginning of the year.  Argument taken.
181               J => Set time to modified Julian date.  Argument taken.
182               s => Set time to seconds since January 1, 1970.  Argument taken.
183
184           These characters represent modifiers to the time set using the
185           above characters:
186
187               B => Add months to time.  Argument taken.
188               W => Add weeks to time.  Argument taken.
189               D => Add days counted from 1 to time.  Argument taken.
190               d => Add days counted from 0 to time.  Argument taken.
191               H => Add hours to time.  Argument taken.
192               M => Add minutes to time.  Argument taken.
193               S => Add seconds to time.  Argument taken.
194
195           If the date and time was successfully set, then it returns the
196           newly set date/time object, otherwise set_time() returns an empty
197           list in a list context, an undefined value in a scalar context, or
198           nothing in a void context and the date and time remain unchanged.
199
200       get_time string
201           Return an array, where each element of the array corresponds to the
202           corresponding strftime() value.  This string should not contain %
203           characters.  This method is a much, much better and faster way of
204           doing
205
206               map {$self->strftime("%$_")} split(//, $string)
207
208       year [year]
209           Return the year.  If an argument is passed to year, then set the
210           year to the the integer part of the argument and then return the
211           newly set year.
212
213       month [month]
214           Return the numerical month (1 = January, 12 = December).  If an
215           argument is passed to month, then set the month to the integer part
216           of the argument and return the newly set month.
217
218       day [day]
219           Return the day of the month.  If an argument is passed to day, then
220           set the day to the integer part of the argument and return the
221           newly set day.
222
223       hours [hours]
224           Return the hours in the day.  If an argument is passed to hours,
225           then set the hours to the integer part of the argument and return
226           the newly set hours.
227
228       minutes [minutes]
229           Return the minutes in the hour.  If an argument is passed to
230           minutes, then set the minutes to the integer part of the argument
231           and return the newly set minutes.
232
233       seconds [seconds]
234           Return the seconds in the minutes.  If an argument is passed to
235           seconds, then set the seconds to the argument and return the newly
236           set seconds.  This argument accepts fractional seconds and will
237           return the fractional seconds.
238
239       serial_day
240           Returns a serial day number representing the date, plus a fraction
241           representing the time since midnight (i.e., noon=0.5).  This is for
242           applications which need an scale index (we use it for positioning a
243           date on a time-series graph axis).  See also set_from_serial_day().
244
245       day_of_year
246           Return the day of the year including the fraction part of the day.
247           Midnight January 1st is day 1, noon January 1st is 1.5, etc.
248
249       julian_day
250           Return the day of the year including the fraction part of the day
251           where time is 0 based.  Midnight January 1st is day 0, noon January
252           1st is 0.5, noon January 2nd is 1.5, etc.
253
254       unix_seconds_since_epoch
255           Return the time in seconds between the object and January 1, 1970
256           UTC.
257
258       gps_seconds_since_epoch
259           Return the time in seconds between the object and January 6, 1980
260           UTC.
261
262       gps_week_seconds_day
263           Return an array consisting of the GPS week 0 filled to four spaces,
264           the number of seconds into the GPS week, and the GPS day, where day
265           0 is Sunday.
266
267       gps_week
268           Return the GPS week of the object.  The returned number is 0 filled
269           to four digits.
270
271       gps_seconds
272           Return the number of seconds into the current GPS week for the
273           current object.
274
275       gps_day
276           Return the GPS day of the week for the current object, where day 0
277           is Sunday.
278
279       copy
280           Return an identical copy of the current object.
281
282       clone other_dt
283           Set this DateTime::Precise equal to other_dt.
284
285       dprintf string
286           Returns string with substitutions:
287
288               %x     number zero-padded to 2 digits (ie, '02')
289               %C<-x> number space-padded to 2 digits (ie, ' 2')
290               %^x    unpadded number (ie, '2')
291               %~x    3-letter abbrev corresponding to value (%M and %w only)
292               %*x    full name corresponding to value (%M and %w only)
293               %%     '%'
294
295           where x is one of:
296
297               h      hours (0..23)
298               m      minutes (0..59)
299               s      seconds (0..59)
300               D      day of the month (1..31)
301               M      month (1..12)
302               Y      years since 1900 (ie, 96)
303               W      USGS water year (year+1 for months Oct-Dec)
304               w      day of the week (0..6, or "Mon", etc.)
305               E      internal string (no ~^*-)
306
307           so, for example, to get a string in datetime format, you would pass
308           a string of '%^Y.%M.%D %h:%m:%s', or, to get a ctime-like string,
309           you would pass: '%~w %~M %-D %h:%m:%s CDT %^Y' (presuming you're in
310           the CDT.  Maybe timezone support will show up some day).
311
312           The US Geological Survey (USGS) likes midnight to be 24:00:00 of
313           the previous day, not 00:00:00 of the day people expect.  If
314           $DateTime::Precise::USGSMidnight is set, dprintf will always print
315           midnight as 24:00:00 and the date returned from dprintf will have
316           the previous day's date.  Regardless, time is always stored
317           internally as 00:00:00.
318
319       dscanf format string
320           Takes a format string format, and use it to read the date and time
321           fields from the supplied string.  The current date and time is
322           unchanged if dscanf fails.
323
324           All format characters recognized by dprintf() are valid.  Two
325           additional characters are recognized, 'U' which sets the time to
326           the local time/date using the number of seconds since Unix epoch
327           time and 'u' which sets the time to GMT time/date using the number
328           of seconds since Unix epoch time.  Unless exact characters are
329           supplied or format characters are concatenated, will separate on
330           non-matching characters.
331
332       strftime format
333           Just like the strftime() function call.  This version is based on
334           the Solaris manual page.  format is a string containing of zero or
335           more conversion specifications.  A specification character consists
336           of a '%' (percent) character followed by one conversion characters
337           that determine the conversion specifications behavior.  All
338           ordinary characters are copied unchanged to the return string.
339
340           The following GPS specific conversions are supported in this
341           strftime:
342               %s    the seconds since UTC January 1, 1970
343               %G    the GPS week (4 digits with leading 0's)
344               %g    the GPS seconds into the GPS week with no leading zeros
345               %f    the GPS day where 0 = Sunday, 1 = Monday, etc
346               %F    the GPS day where 1 = Sunday, 2 = Monday, etc
347
348           The following standard conversions are understood:
349
350               %%    the same as %
351               %a    the abbreviated weekday name
352               %A    the full weekday name
353               %b    the abbreviated month name
354               %B    the full month name
355               %c    the appropriate date and time representation
356               %C    century number (the year divided by 100 and truncated to an
357                     integer as a decimal number [1,99]); single digits are
358                     preceded by 0
359               %d    day of month [1,31]; single digits are preceded by 0
360               %D    date as %m/%d/%y
361               %e    day of month [1,31]; single digits are preceded by a space
362               %h    locale's abbreviated month name
363               %H    hour (24-hour clock) [0,23]; single digits are preceded by 0
364               %I    hour (12-hour clock) [1,12]; single digits are preceded by 0
365               %j    day number of year [1,366]; single digits are preceded by 0
366               %k    hour (24-hour clock) [0,23]; single digits are preceded by
367                     a blank
368               %l    hour (12-hour clock) [1,12]; single digits are preceded by
369                     a blank
370               %m    month number [1,12]; single digits are preceded by 0
371               %M    minute [00,59]; leading zero is permitted but not required
372               %n    insert a newline
373               %p    either AM or PM
374               %r    appropriate time representation in 12-hour clock format with
375                     %p
376               %R    time as %H:%M
377               %S    seconds [00,61]
378               %t    insert a tab
379               %T    time as %H:%M:%S
380               %u    weekday as a decimal number [1,7], with 1 representing Sunday
381               %U    week number of year as a decimal number [00,53], with Sunday
382                     as the first day of week 1
383               %V    week number of the year as a decimal number [01,53], with
384                     Monday as the first day of the week. If the week containing 1
385                     January has four or more days in the new year, then it is
386                     considered week 1; otherwise, it is week 53 of the previous
387                     year, and the next week is week 1.
388               %w    weekday as a decimal number [0,6], with 0 representing Sunday
389               %W    week number of year as a decimal number [00,53], with Monday
390                     as the first day of week 1
391               %x    locale's appropriate date representation
392               %X    locale's appropriate time representation
393               %y    year within century [00,99]
394               %Y    year, including the century (for example 1993)
395               %Z    Always GMT
396
397       asctime
398           Return a string such as 'Fri Apr 3 12:13:44 GMT 1998'.  This is
399           equivalent to strftime('%c').
400
401   Incrementing and rounding
402       There are many subroutines of the format 'func_unit', where func is one
403       of (inc, dec, floor, ceil, round) and unit is one of (second, minute,
404       hour, day, month, year) [second and minute can be abbreviated as sec
405       and min respectively].
406
407       inc_unit(i) increments the date by i units (i defaults to 1 if no
408       parameter is supplied).  For days through seconds, fractional
409       increments are allowed.  However, for months and years, only the
410       integer part of the increment is used.
411
412       dec_unit(i) identical to inc_unit("-i").
413
414       round_unit() rounds the date to the nearest unit.  Rounds years down
415       for Jan-Jun, and up for Jul-Dec; months down for 1st-15th and up for
416       16th and later; days round up on or after 12:00:00; hours on or after
417       xx:30:00, minutes on or after 30 seconds; seconds on or after 0.5
418       seconds.
419
420       floor_unit() rounds the date down to the earliest time for the current
421       unit.  For example, floor_month() rounds to midnight of the first day
422       of the current month, floor_day() to midnight of the current day, and
423       floor_hour() to xx:00:00.
424
425       ceil_unit() is the complementary function to floor.  It rounds the date
426       up, to the earliest time in the next unit.  E.g., ceil_month() makes
427       the date midnight of the first day of the next month.
428
429   Overloaded operators
430       Addition, subtraction, and comparison operators are overloaded, as well
431       as the string representation of a date object.
432
433           # create a new object
434           $x = DateTime::Precise->new('1996.05.05 05:05:05');
435           # copy it
436           $y = $x;
437           # increment x by one second
438           $x++;
439           # decrement by a day
440           $y = $y - 86400;
441           # test em
442           print ($x < $y ? "x is earlier\n" : "y is earlier\n");
443           # get the difference
444           print "The difference between x and y is ", $x-$y, " seconds.\n";
445
446       If $x is a date object, "$x + $i" is identical to $x->inc_sec($i).
447
448       There are two possible results from subtraction.  "$x - $i", where $i
449       is a number, will return a new date, $i seconds before $x. "$x - $y",
450       where $y is another date object, is identical to $x->diff($y).
451
452       Comparison operators (<,>,==,etc) work as one would expect.
453

PUBLIC CONSTANTS

455       The following variables are not imported into your package by default.
456       If you want to use them, then use
457
458           use DateTime::Precise qw(:TimeVars);
459
460       in your package.  Otherwise, you can use the fully qualified package
461       name, such as $DateTime::Precise::USGSMidnight.
462
463       $USGSMidnight
464           Set this to 1 if you want midnight represented as 24:00:00 of the
465           previous day.  The default value is 0 which does not change the
466           behavior of midnight.  To use this variable in your code, load the
467           DateTime::Precise module like this:
468
469               use DateTime::Precise qw($USGSMidnight);
470
471           Setting this only changes the output of dprintf for date and times
472           that are exactly midnight.
473
474       @MonthDays
475           Days per month in a non-leap year.  This array is 1 indexed, so 0
476           is December, 1 is January, etc.
477
478       @MonthName
479           Month names.  This array is 1 indexed, so 0 is December, 1 is
480           January, etc.
481
482       @MonthAbbrev
483           Month abbreviated names.  This array is 1indexed, so 0 is Dec, 1 is
484           Jan, etc.
485
486       @WeekName
487           Names of the week, 0 indexed.  So 0 is Sunday, 1 is Monday, etc.
488
489       @WeekAbbrev
490           Abbreviated names of the week, 0 indexed.  So 0 is Sun, 1 is Mon,
491           etc.
492
493       &Secs_per_week
494           The number of seconds in one week (604800).
495
496       &Secs_per_day
497           The number of seconds in one day (86400).
498
499       &Secs_per_hour
500           The number of seconds in one hour (3600).
501
502       &Secs_per_minute
503           The number of seconds in one minute (60).
504
505       &JANUARY_1_1970
506           Subroutine returning the Unix epoch time January 1, 1970 UTC.
507
508       &JANUARY_6_1980
509           Subroutine returning the GPS epoch time January 6, 1980 UTC.
510

PUBLIC SUBROUTINES

512       IsLeapYear(year)
513           Returns true if the argument is a leap year.
514
515       DaysInMonth(month, year)
516           Returns the number of days in the month.
517

IMPLEMENTATION

519       This package is based on the DateTime package written by Greg Fast
520       <gdfast@usgs.gov>.  The _week_of_year routine is based on the
521       Date_WeekOfYear routine from the Date::DateManip package written by
522       Sullivan Beck.
523
524       Instead of using the string representation used in the original
525       DateTime package, this package represents the time internally as a
526       seven element array, where the elements correspond to the year, month,
527       day, hours, minutes, seconds, and fractional seconds.
528

AUTHOR

530       Contact: Blair Zajac <blair@orcaware.com>.  The original version of
531       this module was based on DateTime written by Greg Fast
532       <gdfast@usgs.gov>.
533

POD ERRORS

535       Hey! The above document had some coding errors, which are explained
536       below:
537
538       Around line 2024:
539           =back doesn't take any parameters, but you said =back 4
540
541       Around line 2330:
542           =back doesn't take any parameters, but you said =back 4
543
544       Around line 2398:
545           '=item' outside of any '=over'
546
547       Around line 2457:
548           You forgot a '=back' before '=head1'
549
550       Around line 2469:
551           =back doesn't take any parameters, but you said =back 4
552
553
554
555perl v5.34.0                      2021-07-22              DateTime::Precise(3)
Impressum