Handler::Delta(3)

🦋 NAME 🦋

okay bestie, welcome to Handler::Delta(3) 💅 — aka Date::Handler::Delta, the Time lapse object ✨

---

🌸 SYNOPSIS 🌸

no thoughts, just vibes, and also code:

  use Date::Handler::Delta;

   my $delta = new Date::Handler::Delta([3,1,10,2,5,5]);
   my $delta = new Date::Handler::Delta({
                                                        years => 3,
                                                        months => 1,
                                                        days => 10,
                                                        hours => 2,
                                                        minutes => 5,
                                                        seconds => 5,
                                                });

   $delta->new                          (More information in perldoc Date::Handler::Delta)
   $delta->Months()                     Number of months in delta
   $delta->Seconds()                    Number of seconds in delta
   $delta->AsScalar()                   "%d months and %d seconds"
   $delta->AsNumber()                   "%d-%d-%d"
   $delta->AsArray()                    [y,m,ss]
   $delta->AsHash()                     { months => m, seconds => ss }

   $date + $delta = Date::Handler
   $date - $delta = Date::Handler
   $date - $date2 = Date::Handler::Delta
   $date + n = (+n seconds)
   $date - n = (-n seconds)

   $delta + $delta = Date::Handler::Delta
   $delta - $delta = Date::Handler::Delta
   $delta * n = Date::Handler::Delta
   $delta / n = Date::Handler::Delta
   $delta + n = (+n seconds)
   $delta - n = (-n seconds)

like, look at all that math going on. it's giving calculator but make it fashion 🧮✨

---

🎀 DESCRIPTION 🎀

Date::Handler::Delta is an object that represents a lapse of time. a whole chunk of time, just vibing as a little object 🕰️

its internal representation of a time lapse is reduced to months and seconds. that's it. that's the whole personality.

and here's the important part, bestie: a Date::Handler::Delta object is always relative to a Date::Handler object. its calculation methods don't wake up until the delta gets applied to a date. so it's lowkey just sitting there, waiting for its moment, main character energy, until you hand it a date. then it slays 🔥

---

💜 IMPLEMENTATION 💜

implementation details, come get y'all juice 🧃

✨ Creating a Date::Handler::Delta object ✨

the new() constructor receives only one argument, and it has to be an array reference or a hash reference:

        my $delta = Date::Handler::Delta->new([1,3,5,0,0]);
        my $delta = Date::Handler::Delta->new({
                                                years => 1,
                                                months => 3,
                                                days => 5,
                                                minutes= > 0,
                                                seconds => 0,
                                        });

⚠️ yes, that minutes= > 0 is exactly how it's written up in here, space and all. copying it character-for-character because that's the rule and also because we respect the source 💅

• As array reference, the order if years, months, days, minutes seconds
• As hash reference, the keys are years, months, days, minutes, seconds.

so like, pick your fighter: array or hash. both valid, both iconic 🫶

🌈 Accessors 🌈

you can access the data inside the object using any of the provided methods. these methods are detailed in the SYNOPSIS up above. yes, scroll up, they're right there, go look 👀

since Date::Handler uses operator overloading, you can 'apply' a Delta object on an absolute date simply by using built-in operators. no fancy method calls, just math. periodt ✨

Example:

        #A Delta of 1 year.
        my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);

        my $date = new Date::Handler({ date => time } );

        #$newdate is now one year in the furure.
        my $newdate = $date+$delta;

(and yes, "furure" — that's the original's spelling, we keep it, we treasure it 🙈)

🦄 Operator overload special cases 🦄

the Date::Handler overloaded operator have special cases. refer to the SYNOPSIS to get a description of each overloaded operator's behaviour.

one special case of the overload is when adding an integer n to a Date::Handler's reference. this is treated as if n was in seconds. same thing for substraction. so n is never, like, days. it's seconds. do not be fooled, bestie ⏱️

Example Uses of the overload:

        my $date = new Date::Handler({ date =>
                                        {
                                                year => 2001,
                                                month => 5,
                                                day => 14,
                                                hour => 5,
                                                min => 0,
                                                sec => 0,
                                        }});
        #Quoted string overload
        print "Current date is $date\n";

        my $delta = new Date::Handler::Delta({ days => 5, });

        #'+' overload, now, $date is 5 days in the future.
        $date += $delta;

        #Small clock. Not too accurate, but still ;)
        while(1)
        {
                #Add one second to the date. (same as $date + 1)
                $date++;
                print "$date\n";
                sleep(1);
        }

a whole little clock. not too accurate, but still 😌🕐 we love a humble icon.

---

💀 BUGS (known) 💀

🚨 listen up, this is the important part 🚨

deltas going after 2038 are not handled by this module yet. (POSIX)

deltas before 1902 are not handled by this module. (POSIX)

so like, 1902 to 2038. that's the window. outside of it? no cap, it's not handled. plan accordingly bestie 😭

if you find bugs with this module, do not hesitate to contact the author. your comments and rants are welcomed :) — yes, rants. they WANT your rants. go off, king 👑

---

📝 TODO 📝

refine reduction to simplest expression of the delta.

that's it. one item. short and mysterious. it's giving "we'll get to it" ✨

---

👑 COPYRIGHT 👑

Copyright(c) 2001 Benoit Beausejour <bbeausej@pobox.com>

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Portions Copyright (c) Philippe M. Chiasson <gozer@cpan.org>

Portions Copyright (c) Szabó, Balázs <dlux@kapu.hu>

Portions Copyright (c) Larry Rosler

---

🌟 AUTHOR 🌟

Benoit Beausejour <bbeausej@pobox.com>

---

🔍 SEE ALSO 🔍

• Date::Handler(1).
• Date::Handler::Range(1).
• Class::Date(1).
• Time::Object(1).
• Date::Calc(1).
• perl(1).

---

and that's the whole page, bestie 💖 this was Handler::Delta(3) from perl v5.42.0, dated 2025-07-25 — literally the version and the date, right here, in a cute little sign-off, because we always cite our sources 🎀✨ go forth and compute your deltas responsibly 🦋💅