/ 
Time-Stamp-1.000
River stage one • 2 direct dependents • 2 total dependents
/ Time::Stamp

NAME

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

VERSION

version 1.000

SYNOPSIS

use Time::Stamp 'gmstamp';

use Time::Stamp localstamp => { -as => 'ltime', format => 'compact' };

use Time::Stamp -stamps => { dt_sep => ' ', date_sep => '/' };

# the default configurations of localstamp and gmstamp
# are available without importing into your namespace
# but this is probably less useful
$stamp = Time::Stamp::gmstamp($time);

DESCRIPTION

This module makes it easy to include timestamp functions that are simple, easily readable, and fast. For simple timestamps perl's built-in functions are all you need: time|perlfunc/time, gmtime|perlfunc/gmtime (or localtime|perlfunc/localtime), and sprintf|perlfunc/sprintf...

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 call time() to get a seconds-since-epoch integer.

Sometimes you get a seconds-since-epoch integer from another function (like stat() 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 into localtime() to figure out when that actually was.

You can pass the timestamp to scalar localtime($sec) (or scalar 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 from "localtime" in perlfunc and "gmtime" in perlfunc without incurring the resource cost of DateTime (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: ''

The following formats are predefined:

default => see above descriptions
iso8601 => \%default
rfc3339 => \%default
w3cdtf  => \%default
  "2010-01-02T13:14:15"    # local
  "2010-01-02T13:14:15Z"   # gm

easy    => 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"  # gm

compact => condense date and time components and set dt_sep to '_'
  "20100102_131415"        # local
  "20100102_131415Z"       # gm

numeric => all options are '' so that only numbers remain
  "20100102131415"         # both

Currently there is no attempt to guess the time zone. By default gmstamp sets tz to 'Z' (which you can override if desired). If you are using gmstamp (recommended for transmitting to another computer) you don't need anything else. If you are using localstamp 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::Timezone
use 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 core
use 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 uses Sub::Exporter to enable you to customize your timestamp function but still create it as easily as possible.

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

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

use Time::Stamp gmstamp => { dt_sep => ' ', tz => ' UTC' };

use Time::Stamp gmstamp => { -as => shorttime, format => 'compact' };

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

  • If called with no arguments time() (now) will be used.

  • A single argument should be an integer (like that returned from time() or stat()).

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

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 use Time::Local just to get the integer back.

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

gmstamp

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

Returns a string according to the format specified in the import call.

By default this function sets tz to 'Z' since gmtime() returns values in UTC (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);

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.

-stamps

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

SEE ALSO

TODO

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

  • Include the fractional portion of the seconds if present?

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.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-time-stamp at rt.cpan.org, or through the web interface at http://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

http://github.com/magnificent-tears/Time-Stamp/tree

git clone git://github.com/magnificent-tears/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.