.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DateTime::Format::Epoch 3pm" .TH DateTime::Format::Epoch 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DateTime::Format::Epoch \- Convert DateTimes to/from epoch seconds .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use DateTime::Format::Epoch; \& \& my $dt = DateTime\->new( year => 1970, month => 1, day => 1 ); \& my $formatter = DateTime::Format::Epoch\->new( \& epoch => $dt, \& unit => \*(Aqseconds\*(Aq, \& type => \*(Aqint\*(Aq, # or \*(Aqfloat\*(Aq, \*(Aqbigint\*(Aq \& skip_leap_seconds => 1, \& start_at => 0, \& local_epoch => undef, \& ); \& \& my $dt2 = $formatter\->parse_datetime( 1051488000 ); \& # 2003\-04\-28T00:00:00 \& \& $formatter\->format_datetime($dt2); \& # 1051488000 .Ve .SH "DESCRIPTION" .IX Header "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. .SH "METHODS" .IX Header "METHODS" .IP "\(bu" 4 new( ... ) .Sp Constructor of the formatter/parser object. It can take the following parameters: \*(L"epoch\*(R", \*(L"unit\*(R", \*(L"type\*(R", \*(L"skip_leap_seconds\*(R", \*(L"start_at\*(R", \&\*(L"local_epoch\*(R" and \*(L"dhms\*(R". .Sp 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. .Sp The unit parameter can be \*(L"seconds\*(R", \*(L"milliseconds, \*(R"microseconds\*(L" or \&\*(R"nanoseconds\*(L". The default is \*(R"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. .Sp The type parameter specifies the type of the return value. It can be \&\*(L"int\*(R" (returns integer value), \*(L"float\*(R" (returns floating point value), or \*(L"bigint\*(R" (returns Math::BigInt value). The default is either \*(L"int\*(R" (if the unit is \*(L"seconds\*(R"), or \*(L"bigint\*(R" (if the unit is nanoseconds). .Sp The default behaviour of this module is to skip leap seconds. This is what (most versions of?) \s-1UNIX\s0 do. If you want to include leap seconds, set skip_leap_seconds to false. .Sp 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 \f(CW\*(C`format_datetime\*(C'\fR will then depend on the timezone of the object you pass to \f(CW\*(C`format_datetime\*(C'\fR. .Sp 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 \s-1NASA,\s0 for the so called Mission Elapsed Time. For example, 2/03:45:18 \s-1MET\s0 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. .IP "\(bu" 4 format_datetime($datetime) .Sp Given a DateTime object, this method returns the number of seconds since the epoch. .IP "\(bu" 4 parse_datetime($secs) .Sp Given a number of seconds, this method returns the corresponding DateTime object. .SH "BUGS" .IX Header "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. .SH "SUPPORT" .IX Header "SUPPORT" Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details. .SH "AUTHOR" .IX Header "AUTHOR" Eugene van der Pijll .SH "COPYRIGHT" .IX Header "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. .SH "SEE ALSO" .IX Header "SEE ALSO" DateTime .PP datetime@perl.org mailing list