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 (or localtime), and 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).

For simple timestamps you can get the data you need from localtime and gmtime 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.

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:

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

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 of time() in Time::HiRes for more information.

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.

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

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

In list context they return the list that would have been sent to Time::Local which is similar to the one returned by gmtime and localtime: seconds, minutes, hours, day, month (0-11), year (-1900). NOTE that the wday, yday, and isdst parameters (the last three elements returned from localtime or gmtime) are not returned because they are not easily determined from the stamp. Besides Time::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 the regexp 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 the Time::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.