DateTime::Format::Epoch(3pm)

1DateTime::Format::EpochU(s3e)r Contributed Perl DocumentaDtaitoenTime::Format::Epoch(3)
2
3
4

NAME

6       DateTime::Format::Epoch - Convert DateTimes to/from epoch seconds
7

SYNOPSIS

9         use DateTime::Format::Epoch;
10
11         my $dt = DateTime->new( year => 1970, month => 1, day => 1 );
12         my $formatter = DateTime::Format::Epoch->new(
13                             epoch          => $dt,
14                             unit           => 'seconds',
15                             type           => 'int',    # or 'float', 'bigint'
16                             skip_leap_seconds => 1,
17                             start_at       => 0,
18                             local_epoch    => undef,
19                         );
20
21         my $dt2 = $formatter->parse_datetime( 1051488000 );
22          # 2003-04-28T00:00:00
23
24         $formatter->format_datetime($dt2);
25          # 1051488000
26

DESCRIPTION

28       This module can convert a DateTime object (or any object that can be
29       converted to a DateTime object) to the number of seconds since a given
30       epoch.  It can also do the reverse.
31

METHODS

33       •   new( ... )
34
35           Constructor of the formatter/parser object. It can take the
36           following parameters: "epoch", "unit", "type", "skip_leap_seconds",
37           "start_at", "local_epoch" and "dhms".
38
39           The epoch parameter is the only required parameter. It should be a
40           DateTime object (or at least, it has to be convertible to a
41           DateTime object). This datetime is the starting point of the day
42           count, and is usually numbered 0. If you want to start at a
43           different value, you can use the start_at parameter.
44
45           The unit parameter can be "seconds", "milliseconds, "microseconds"
46           or "nanoseconds". The default is "seconds". If you need any other
47           unit, you must specify the number of units per second. If you
48           specify a number of units per second below 1, the unit will be
49           longer than a second.  In this way, you can count days: unit =>
50           1/86_400.
51
52           The type parameter specifies the type of the return value. It can
53           be "int" (returns integer value), "float" (returns floating point
54           value), or "bigint" (returns Math::BigInt value). The default is
55           either "int" (if the unit is "seconds"), or "bigint" (if the unit
56           is nanoseconds).
57
58           The default behaviour of this module is to skip leap seconds. This
59           is what (most versions of?) UNIX do. If you want to include leap
60           seconds, set skip_leap_seconds to false.
61
62           Some operating systems use an epoch defined in the local timezone
63           of the computer. If you want to use such an epoch in this module,
64           you have two options. The first is to submit a DateTime object with
65           the appropriate timezone. The second option is to set the
66           local_epoch parameter to a true value. In this case, you should
67           submit an epoch with a floating timezone. The exact epoch used in
68           "format_datetime" will then depend on the timezone of the object
69           you pass to "format_datetime".
70
71           Most often, the time since an epoch is given in seconds. In some
72           circumstances however it is expressed as a number of days, hours,
73           minutes and seconds. This is done by NASA, for the so called
74           Mission Elapsed Time. For example, 2/03:45:18 MET means it has been
75           2 days, 3 hours, 45 minutes, and 18 seconds since liftoff. If you
76           set the dhms parameter to true, format_datetime returns a four
77           element list, containing the number of days, hours, minutes and
78           seconds, and parse_datetime accepts the same four element list.
79
80       •   format_datetime($datetime)
81
82           Given a DateTime object, this method returns the number of seconds
83           since the epoch.
84
85       •   parse_datetime($secs)
86
87           Given a number of seconds, this method returns the corresponding
88           DateTime object.
89

BUGS

91       I think there's a problem when you define a count that does not skip
92       leap seconds, and uses the local timezone. Don't do that.
93

SUPPORT

95       Support for this module is provided via the datetime@perl.org email
96       list. See http://lists.perl.org/ for more details.
97

AUTHOR

99       Eugene van der Pijll <pijll@gmx.net>
100

COPYRIGHT

102       Copyright (c) 2003-2006 Eugene van der Pijll.  All rights reserved.
103       This program is free software; you can redistribute it and/or modify it
104       under the same terms as Perl itself.
105