NAME

Time::Stamp - Easy, readable, efficient timestamp functions

VERSION

version 1.300

SYNOPSIS

# import customized functions to make easy-to-use timestampsuse Time::Stamp 'gmstamp';my $now = gmstamp();my $mtime = gmstamp( (stat($file))[9] );  # $mtime is something like "2012-05-18T10:52:32Z"use Time::Stamp localstamp => { -as => 'ltime', format => 'compact' };  # ltime() will return something like "20120518_105232"use Time::Stamp -stamps => { dt_sep => ' ', date_sep => '/', us => 1 };  # localstamp() will return something like "2012/05/18 10:52:32.123456"# inverse functions to parse the stampsuse Time::Stamp 'parsegm';my $seconds = parsegm($stamp);use Time::Stamp parselocal => { -as => 'parsel', regexp => qr/$pattern/ };use Time::Stamp -parsers => { regexp => qr/$pattern/ };# the default configurations of each function# are available without importing into your namespace$stamp = Time::Stamp::gmstamp($time);$time  = Time::Stamp::parsegm($stamp);# use shortcuts for specifying desired format, useful for one-liners:qx/perl -MTime::Stamp=local-compact -E 'say localstamp'/;# with milliseconds:qx/perl -MTime::Stamp=local-compact-ms -E 'say localstamp'/;# with microseconds:qx/perl -MTime::Stamp=local-compact-us -E 'say localstamp'/;

DESCRIPTION

This module makes it easy to include timestamp functions that are simple, easy to read, easy to parse, and fast. For simple timestamps perl's built-in functions are all you need:time,gmtime (orlocaltime), andsprintf...

Sometimes you desire a simple timestamp to add to a file name or use as part of a generated data identifier. The fastest and easiest thing to do is calltime() to get a seconds-since-epoch integer.

Sometimes you get a seconds-since-epoch integer from another function (likestat() for instance) and maybe you want to store that in a database or send it across the network.

This integer timestamp works for these purposes, but it's not easy to read.

If you're looking at a list of timestamps you have to fire up a perl interpreter and copy and paste the timestamp intolocaltime() to figure out when that actually was.

You can pass the timestamp toscalar localtime($sec) (orscalar gmtime($sec)) but that doesn't sort well or parse easily, isn't internationally friendly, and contains characters that aren't friendly for file names or URIs (or other places you may want to use it).

See"Time and Date" in perlport for more discussion on useful timestamps.

For simple timestamps you can get the data you need fromlocaltime andgmtime without incurring the resource cost ofDateTime (or any other object for that matter).

So the aim of this module is to provide simple timestamp functions so that you can have easy-to-use, easy-to-read timestamps efficiently.

FORMAT

For reasons listed elsewhere the timestamps are always in order from largest unit to smallest: year, month, day, hours, minutes, seconds and are always two digits, except the year which is always four.

The other characters of the stamp are configurable:

• date_sep - Character separating date components; Default:'-'

• dt_sep - Character separating date and time; Default:'T'

• time_sep - Character separating time components; Default:':'

• tz_sep - Character separating time and timezone; Default:''

• tz - Time zone designator; Default:''

• frac - Digits of fractional seconds to show; Default: no fraction

• ms - Boolean shortcut: milliseconds; If true, same asfrac => 3

• us - Boolean shortcut: microseconds; If true, same asfrac => 6

The following formats are predefined:

default => see above descriptionsiso8601 => \%defaultrfc3339 => \%defaultw3cdtf  => \%default  "2010-01-02T13:14:15"    # local  "2010-01-02T13:14:15Z"   # gmeasy    => like default but with a space as dt_sep and tz_sep (easier to read)  "2010-01-02 13:14:15"    # local  "2010-01-02 13:14:15 Z"  # gmcompact => condense date and time components and set dt_sep to '_'  "20100102_131415"        # local  "20100102_131415Z"       # gmnumeric => all options are '' so that only numbers remain  "20100102131415"         # both

Currently there is no attempt to guess the time zone. By defaultgmstamp setstz to'Z' (which you can override if desired). If you are usinggmstamp (recommended for transmitting to another computer) you don't need anything else. If you are usinglocalstamp you are probably keeping the timestamp on that computer (like the stamp in a log file) and you probably aren't concerned with time zone since it isn't likely to change.

If you want to include a time zone (other than'Z' for UTC) the standards suggest using the offset value (like-0700 or+12:00). If you would like to determine the time zone offset you can do something like:

use Time::Zone (); # or Time::Timezoneuse Time::Stamp localtime => { tz => Time::Zone::tz_offset() };

If, despite the recommendations, you want to use the local time zone code:

use POSIX (); # included in perl coreuse Time::Stamp localtime => { tz => POSIX::strftime('%Z', localtime) };

These options are not included in this module since they are not recommended and introduce unnecessary overhead (loading the aforementioned modules).

EXPORTS

This module usesSub::Exporter to enable you to customize your timestamp function but still create it as easily as possible.

The customizations are done at import and stored in the custom function returned to make the resulting function as fast as possible.

The following groups and functions are available for export (nothing is exported by default):

-stamps

This is a convenience group for importing both"gmstamp" and"localstamp".

Each timestamp export accepts any of the keys listed in"FORMAT" as well asformat which can be the name of a predefined format.

use Time::Stamp '-stamps';use Time::Stamp  -stamps => { format => 'compact' };use Time::Stamp gmstamp => { dt_sep => ' ', tz => ' UTC' };use Time::Stamp localstamp => { -as => shorttime, format => 'compact' };

Each timestamp function will return a string according to the time as follows:

• If called with no argumentstime() (now) will be used

  (or"gettimeofday" in Time::HiRes for fractional seconds).

• A single argument should be an integer (like that returned fromtime() orstat()).

  If a floating point number is provided (and fractional seconds were part of the format) the fraction will be preserved (according to the specified precision).

  Note: You may want to stringify a floating point number yourself in order to control the precision rather than be subject to the rounding of the default stringification:

  localstamp(sprintf "%.6f", $timestamp)

  See "NOTE 2" in the description oftime() inTime::HiRes for more information.

• More than one argument is assumed to be the list returned fromgmtime() orlocaltime() which can be useful if you previously called the function and don't want to do it again.

  If the first argument (seconds) is a floating point number (and fractional seconds were part of the format) the fraction will be preserved (according to the specified precision).

Most commonly the 0 or 1 argument form would be used, but the shortcut of using a time array is provided in case you already have the array so that you don't have to useTime::Local just to get the integer back.

gmstamp

$stamp = gmstamp(); # equivalent to gmstamp(time())$stamp = gmstamp($seconds);$stamp = gmstamp(@gmtime);

This returns a string according to the format specified in the import call.

By default this function setstz to'Z' sincegmtime() returns values inUTC (no time zone offset).

This is the recommended stamp as it is by default unambiguous and useful for transmitting to another computer.

localstamp

$stamp = localstamp(); # equivalent to localstamp(time())$stamp = localstamp($seconds);$stamp = localstamp(@localtime);

This returns a string according to the format specified in the import call.

By default this function does not include a time zone indicator.

This function can be useful for log files or other values that stay on the machine where time zone is not important and/or is constant.

-parsers

This is a convenience group for importing both"parsegm" and"parselocal".

use Time::Stamp '-parsers';use Time::Stamp  -parsers => { regexp => qr/pattern/ };use Time::Stamp 'parsegm';use Time::Stamp  parselocal => { -as => 'parsestamp', regexp => qr/pattern/ };

The parser functions are the inverse of the stamp functions. They accept a timestamp and use the appropriate function fromTime::Local to turn it back into a seconds-since-epoch integer.

In list context they return the list that would have been sent toTime::Local which is similar to the one returned bygmtime andlocaltime: seconds, minutes, hours, day, month (0-11), year (-1900).NOTE that thewday,yday, andisdst parameters (the last three elements returned fromlocaltime orgmtime) are not returned because they are not easily determined from the stamp. BesidesTime::Local only takes the first 6 anyway.

If the stamp doesn't match the pattern the function will return undef in scalar context or an empty list in list context.

An alternate regular expression can be supplied as theregexp parameter during import. The default pattern will match any of the named formats.

The pattern must capture 6 groups in the appropriate order: year, month, day, hour, minute, second. If you're doing something more complex you probably ought to be using one of the modules listed in"SEE ALSO".

An optional 7th group can be used to capture the fractional seconds. If only 6 groups are used, the 6th capture (seconds) will be checked for a fraction. The fraction will be separated from the whole number before being passed through theTime::Local functions then appended to the result (the number returned in scalar context, or to the first element returned in list context) in an attempt to provide the most expected/reliable result.

parsegm

$seconds = parsegm($stamp);@gmtime  = parsegm($stamp);

This is the inverse of"gmstamp". It parses a timestamp (like the ones created by this module) and uses"timegm" in Time::Local to turn it back into a seconds-since-epoch integer.

parselocal

$seconds   = parselocal($stamp);@localtime = parselocal($stamp);

This is the inverse of"localstamp". It parses a timestamp (like the ones created by this module) and uses"timelocal" in Time::Local to it them back into a seconds-since-epoch integer.

SHORTCUTS

There are also shortcuts available in the format oftype-format that export the appropriate function using the named format.

For example:

• local-compact exports a"localstamp" function using thecompact format

• gm-easy exports a"gmstamp" function using theeasy format

This makes the module easier to use on the command line:

perl -MTime::Stamp=local-compact -E 'say localstamp'

Rather than:

perl -E 'use Time::Stamp localstamp => { format => "compact" }; say localstamp'

Any of the predefined formats named in"FORMAT" can be used in the shortcut notation.

Additionally recognized flags include:

• us adds microseconds (6 digit precision):local-easy-us

• ms adds milliseconds (3 digit precision):gm-ms

SEE ALSO

• "Time and Date" in perlport - discussion on using portable, readable timestamps

• "localtime" in perlfunc - built-in function

• "gmtime" in perlfunc - built-in function

• Timestamp::Simple - small, less efficient, non-customizable stamp

• Time::Piece - object-oriented module for working with times

• DateTime::Tiny - object-oriented module "with as little code as possible"

• DateTime - large, powerful object-oriented system

• Time::localtime - small object-oriented/named interface tolocaltime()

• Time::gmtime - small object-oriented/named interface togmtime()

• POSIX - large module containing standard methods includingstrftime()

• http://www.cl.cam.ac.uk/~mgk25/iso-time.html - summary ofISO 8601

• http://www.w3.org/TR/NOTE-datetime -W3CDTF profile ofISO 8601

• http://www.ietf.org/rfc/rfc3339.txt -RFC3339 profile ofISO 8601

TODO

• Allow an option for overwriting the globals so that callinglocaltime in scalar context will return a stamp in the desired format. The normal values will be returned in list context.

SUPPORT

Perldoc

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

perldoc Time::Stamp

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

• Search CPAN

  The default CPAN search engine, useful to view POD in HTML format.

  http://search.cpan.org/dist/Time-Stamp

• RT: CPAN's Bug Tracker

  The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Time-Stamp

• CPAN Ratings

  The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.

  http://cpanratings.perl.org/d/Time-Stamp

• CPAN Testers

  The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.

  http://www.cpantesters.org/distro/T/Time-Stamp

• CPAN Testers Matrix

  The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.

  http://matrix.cpantesters.org/?dist=Time-Stamp

• CPAN Testers Dependencies

  The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.

  http://deps.cpantesters.org/?module=Time::Stamp

Bugs / Feature Requests

Please report any bugs or feature requests by email tobug-time-stamp at rt.cpan.org, or through the web interface athttp://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Stamp. You will be automatically notified of any progress on the request by the system.

Source Code

https://github.com/rwstauner/Time-Stamp

git clone https://github.com/rwstauner/Time-Stamp.git

AUTHOR

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.