DateTi...::Epoch(3pm)

💖 DateTime::Format::Epoch 💖

okay bestie, welcome to DateTime::Format::Epoch (the 3pm perl doc, you know the vibe) — the module that converts DateTimes to and from epoch seconds. it's giving time-travel but make it math. 🕰️✨

---

✨ NAME ✨

DateTime::Format::Epoch — literally just here to convert DateTimes to/from epoch seconds. that's the whole job. slay. 💅

---

🌸 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_seconds => 1,
                    start_at       => 0,
                    local_epoch    => undef,
                );

my $dt2 = $formatter->parse_datetime( 1051488000 );
 # 2003-04-28T00:00:00

$formatter->format_datetime($dt2);
 # 1051488000

see? cute. 1051488000 in, 2003-04-28T00:00:00 out, and back again. it's giving reversible. 🔁

---

🦋 DESCRIPTION 🦋

so basically this module takes a DateTime object (or literally any object that can be converted into a DateTime object, we're not picky 🫶) and turns it into the number of seconds since a given epoch. and it can do the reverse too. both directions. iconic behaviour. 👑

---

💜 METHODS 💜

🎀 new( ... )

the constructor of the formatter/parser object. it can take these parameters: epoch, unit, type, skip_leap_seconds, start_at, local_epoch and dhms. yes, all seven. keep up bestie. ✨

the epoch parameter is the only required one. 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. no cap. 🕐

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. and if you specify a number of units per second below 1, the unit will be longer than a second. so that's how you can count days:

unit => 1/86_400

math ate, honestly. 🧮💅

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"). choose wisely, main character. ✨

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, bestie:

1. submit a DateTime object with the appropriate timezone.
2. 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. so like, a little listy bestie. 🍓

---

🧚 format_datetime($datetime)

given a DateTime object, this method returns the number of seconds since the epoch. that's it. that's the method. 💖

---

⭐ parse_datetime($secs)

given a number of seconds, this method returns the corresponding DateTime object. the reverse girlie. 🔁

---

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

that's a direct quote from the author and honestly? respect the honesty. 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. go bother the mailing list, they're nice. 📧✨

---

👑 AUTHOR 👑

Eugene van der Pijll <pijll@gmx.net>

a legend. fr fr. 🫶

---

💅 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

---

and that's the whole page bestie!! this was DateTi...::Epoch(3pm) from perl v5.34.0, dated 2022-06-13. periodt. 💖✨🎀🦋🌸💅🫶