DateTime::Format::EpocUser Contributed Perl DocumentDateTime::Format::Epoch(3)NAMEDateTime::Format::Epoch - Convert DateTimes to/from epoch seconds
SYNOPSIS
use DateTime::Format::Epoch;
my $dt = DateTime->new( year => 1970, month => 1, day => 1 );
my $formatter = DateTime::Format::Epoch->new(
epoch => $dt,
unit => 'seconds',
type => 'int', # or 'float', 'bigint'
skip_leap_secondss => 1,
start_at => 0,
local_epoch => undef,
);
my $dt2 = $formatter->parse_datetime( 1051488000 );
# 2003-04-28T00:00:00
$formatter->format_datetime($dt2);
# 1051488000
DESCRIPTION
This module can convert a DateTime object (or any object that can be
converted to a DateTime object) to the number of seconds since a given
epoch. It can also do the reverse.
METHODS
· new( ... )
Constructor of the formatter/parser object. It can take the
following parameters: "epoch", "unit", "type", "skip_leap_seconds",
"start_at", "local_epoch" and "dhms".
The epoch parameter is the only required parameter. It should be a
DateTime object (or at least, it has to be convertible to a
DateTime object). This datetime is the starting point of the day
count, and is usually numbered 0. If you want to start at a
different value, you can use the start_at parameter.
The unit parameter can be "seconds", "milliseconds, "microseconds"
or "nanoseconds". The default is "seconds". If you need any other
unit, you must specify the number of units per second. If you
specify a number of units per second below 1, the unit will be
longer than a second. In this way, you can count days: unit =>
1/86_400.
The type parameter specifies the type of the return value. It can
be "int" (returns integer value), "float" (returns floating point
value), or "bigint" (returns Math::BigInt value). The default is
either "int" (if the unit is "seconds"), or "bigint" (if the unit
is nanoseconds).
The default behaviour of this module is to skip leap seconds. This
is what (most versions of?) UNIX do. If you want to include leap
seconds, set skip_leap_seconds to false.
Some operating systems use an epoch defined in the local timezone
of the computer. If you want to use such an epoch in this module,
you have two options. The first is to submit a DateTime object with
the appropriate timezone. The second option is to set the
local_epoch parameter to a true value. In this case, you should
submit an epoch with a floating timezone. The exact epoch used in
"format_datetime" will then depend on the timezone of the object
you pass to "format_datetime".
Most often, the time since an epoch is given in seconds. In some
circumstances however it is expressed as a number of days, hours,
minutes and seconds. This is done by NASA, for the so called
Mission Elapsed Time. For example, 2/03:45:18 MET means it has been
2 days, 3 hours, 45 minutes, and 18 seconds since liftoff. If you
set the dhms parameter to true, format_datetime returns a four
element list, containing the number of days, hours, minutes and
seconds, and parse_datetime accepts the same four element list.
· format_datetime($datetime)
Given a DateTime object, this method returns the number of seconds
since the epoch.
· parse_datetime($secs)
Given a number of seconds, this method returns the corresponding
DateTime object.
BUGS
I think there's a problem when you define a count that does not skip
leap seconds, and uses the local timezone. Don't do that.
SUPPORT
Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.
AUTHOR
Eugene van der Pijll <pijll@gmx.net>
COPYRIGHT
Copyright (c) 2003-2006 Eugene van der Pijll. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
DateTime
datetime@perl.org mailing list
perl v5.14.1 2011-08-29 DateTime::Format::Epoch(3)