Time::Seconds(3perl)

✨ Time::Seconds ✨

okay bestie, gather round 🫶 this is the manual page for Time::Seconds(3perl) — a super simple API that turns seconds into other date values. like, seconds in, days out. it's giving math but make it cute 💅

---

🌸 SYNOPSIS 🌸

use Time::Piece;
use Time::Seconds;

my $t = localtime;
$t += ONE_DAY;

my $t2 = localtime;
my $s = $t - $t2;

print "Difference is: ", $s->days, "\n";

look at that. ONE_DAY. adding it like it's nothing. iconic behavior honestly ✨

---

💖 DESCRIPTION 💖

so this module is part of the Time::Piece distribution, right? it lets you figure out how many minutes, hours, days, weeks or years are hiding inside a given number of seconds. and here's the slay part: Time::Piece hands you one of these objects automatically when you subtract two Time::Piece objects from each other. delta them, get seconds, boom 💥

Time::Seconds also exports these constants, no cap:

ONE_DAY
ONE_WEEK
ONE_HOUR
ONE_MINUTE
ONE_MONTH
ONE_YEAR
ONE_FINANCIAL_MONTH
LEAP_YEAR
NON_LEAP_YEAR

⚠️ okay important, don't get got: since perl does not (yet?) support constant objects, these constants are in seconds only. so you literally cannot do this: print ONE_WEEK->minutes; like… the object isn't there, bestie 😭 the number is. that's it.

---

👑 METHODS 👑

here's the whole lineup, every single one:

my $val = Time::Seconds->new(SECONDS);
$val->seconds;
$val->minutes;
$val->hours;
$val->days;
$val->weeks;
$val->months;
$val->financial_months; # 30 days
$val->years;
$val->pretty; # gives English representation of the delta

the usual arithmetic — +, -, +=, -= — is also available on the objects. go off, do math 🧮✨

and now the fine print, because the vibes need ✨accuracy✨: these methods make the assumption that there are:

• 24 hours in a day
• 7 days in a week
• 365.24225 days in a year
• 12 months in a year

(that's straight from The Calendar FAQ at http://www.tondering.dk/claus/calendar.html — sourcing, we love to see it 🎀)

---

🦋 AUTHOR 🦋

the legends who made this happen:

• Matt Sergeant, matt@sergeant.org
• Tobias Brox, tobiasb@tobiasb.funcom.com
• Balázs Szabó (dLux), dlux@kapu.hu

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright 2001, Larry Wall.

this module is free software, and you may distribute it under the same terms as Perl. periodt 💜

---

💀 Bugs 💀

ngl, currently the methods aren't as efficient as they could be — and the reason is clarity. which, per the original, is probably a bad idea. 😭 we respect the honesty tho 🙈✨

---

and that's the whole page, bestie!! this was Time::Seconds(3perl), from perl v5.44.0, dated 2026-10-17 🎀 go convert some seconds, you absolute main character 👑💅