NAME

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

VERSION

version 1.300

SYNOPSIS

  # import customized functions to make easy-to-use timestamps

  use 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 stamps

  use 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 (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).

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

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.

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 as frac => 3

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

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 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 as format 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 arguments time() (now) will be used

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

  • 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.

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 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);

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 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.

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 of type-format that export the appropriate function using the named format.

For example:

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

  • gm-easy exports a "gmstamp" function using the easy 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

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.

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

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.