/ 
Time-Precise-1.0012
River stage one • 1 direct dependent • 2 total dependents
/ Time::Precise

NAME

Time::Precise - Extending standard time related functions to always include nanoseconds and always use full year.

SYNOPSIS

This module extends standard functions time, localtime, gmtime and sleep to include nanoseconds as a decimal part of the seconds element. It also implements and includes functions forked from Time::Local to work with nanoseconds too, altering its functions timelocal and timegm. It also includes a few extra helper functions described bellow.

Note that this module won't affect any other code or modules, it will only affect the standard functions where it is explicitly used.

use Time::Precise;

# ...or, if you don't want anything exported by default:
use Time::Precise ();

# ...or, to import only a certain function:
use Time::Precise qw(time localtime);

# Time in seconds, but includes nanoseconds. (e.g. 1444217081.0396979)
my $time = time;

# Localtime includes nanoseconds too. (e.g. Wed Oct  7 06:25:44.0032990 2015)
my $localtime = localtime;

# Same applies here accordingly:
my @localtime = localtime;

# Sleep for a second and a half:
sleep 1.5;

# Use functions from Time::Local as normal, but they will work with nanoseconds:
my $seconds = timelocal @localtime;

EXPORT

Functions exported by default: time, localtime, gmtime, sleep, timegm, timelocal, is_valid_date, is_leap_year, time_hashref, gmtime_hashref, get_time_from, get_gmtime_from, localtime_ts, gmtime_ts.

$Time::Precise::PRECISION

$Time::Precise::PRECISION is set by default to 7 and it refers to the number of decimals used for nanoseconds. You can set it to anything else if you want, but generally speaking, setting it to more than 7 will most likely just add zeros to the right (at least in all systems where I've tried it).

This is currently a global setting, so be careful not to alter it if that can cause other packages using this module to expect a different number of decimals. A solution to this when you only need to change the precision in a certain place is to localize it:

use Time::Precise;

my $time = time; # Will have 7 decimals
{
  local $Time::Precise::PRECISION = 3;
  my $short = time; # Will have 3 decimals
}
$time = time; # Will have 7 decimals again

Functions

time, localtime, gmtime

Work just like the regular CORE functions, but specify full year in the response and include nanoseconds as decimals.

localtime_ts, gmtime_ts

Work just like the regular CORE localtime and gmtime functions, except they will return a timestamp SQL style (e.g. 2024-11-27 20:25:30.8543219).

sleep

Works just like the regular CORE sleep, except it accepts fractions of seconds too, including sleeping for less than a second.

timegm, timelocal

Work like the corresponding functions from Time::Local, but they are nanoseconds and full-year enabled for both arguments and response.

is_valid_date($year, $month, $day)

This will return 1 or 0 depending on the date passed being valid.

is_leap_year($year)

This will return 1 or 0 depending on the year passed being a leap year.

time_hashref(<$seconds>), gmtime_hashref(<$gmt_seconds>)

This is a variation of localtime and gmtime respectively. It takes an optional $seconds argument or uses the current time if no argument is passed. It will return a hashref containing the corresponding elements for it. Example:

{
  day          => "07",
  hour         => "06",
  is_leap_year => 0,
  isdst        => 1,
  minute       => 45,
  month        => 10,
  second       => 34.61739,
  wday         => 3,
  yday         => 279,
  year         => 2015,
}

get_time_from(year => $year, month => $month, day => $day, hour => $hour, minute => $minute, second => $second)

get_gmtime_from(year => $year, month => $month, day => $day, hour => $hour, minute => $minute, second => $second)

This function helps you get the corresponding time in seconds for the specified named arguments. All arguments are optional, but if you don't specify anything at all, then it will default to the current date at 0:00 hours. Month is 1..12 based.

Example:

my $time = get_time_from (
  year    => 1975,
  month   => 9,
  day     => 3,
  hour    => 8,
  minute  => 33,
  second  => 12.0067514,
);

# $time is now 178983192.0067514

my $date = localtime $time;

# $date is now Wed Sep  3 08:33:12.0067514 1975

AUTHOR

Francisco Zarabozo, <zarabozo at cpan.org>

BUGS

Please report any bugs or feature requests to bug-time-precise at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Precise. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Time::Precise

You can also look for information at:

SEE ALSO

Time::Local, from which several lines of code have been taken.

LICENSE AND COPYRIGHT

Copyright 2015-2024 Francisco Zarabozo. Parts taken from Time::Local.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.