Badger::Duration(3pm)

💖 NAME 💖

okay so bestie, Badger::Duration is a whole little class for representing durations. that's it, that's the vibe. simple. iconic. periodt. ✨

---

🌸 SYNOPSIS 🌸

use Badger::Duration 'Duration';

my $d = Duration('7 days 4 hours 20 minutes');

print "$d is ", $d->seconds, " seconds\n";

like. look at that. you say "7 days 4 hours 20 minutes" and it just gets you 🫶

---

🦋 DESCRIPTION 🦋

this is a simple module for parsing durations, no cap.

it is ideally suited for stuff like calculating expiry times (think cookies, items in a cache, all that) so you can specify them in human-friendly format, like "4 minutes 20 seconds" — or honestly various alternatives, it's flexible like that 💅

---

✨ EXPORTABLE SUBROUTINES ✨

🎀 DURATION

this is a shortcut alias to Badger::Duration. it's giving nickname energy.

use Badger::Duration 'DURATION';

my $duration = DURATION->new(
    hours   => 4,
    minutes => 20,
);              # same as Badger::Duration->new(...);

💜 Duration()

when you call this subroutine with no arguments, it returns the name of the Badger::Duration class. so it works as an alias for Badger::Duration, exactly like DURATION does:

use Badger::Duration 'Duration';

my $duration = Duration->new(...);  # same as Badger::Duration->new(...);

but when you call it with arguments, it creates a brand new Badger::Duration object. main character behaviour fr:

my $duration = Duration(...);       # same as Badger::Duration->new(...);

---

👑 METHODS 👑

these are the methods defined in addition to the ones inherited from the Badger::Comparable and Badger::Base base classes. the family legacy, if you will.

🌈 new()

constructor method to create a new Badger::Duration object. you can hand it the duration as a single duration parameter:

my $d = Badger::Duration->new(
    duration => '4 minutes 20 seconds'
);

the duration string can contain any number of "<number> <duration>" sequences, separated by whitespace, commas, or the word and. all of these are valid, bestie:

4 minutes 20 seconds
4 minutes,20 seconds
4 minutes, 20 seconds
4 minutes and 20 seconds

the canonical names for durations are: year, month, day, hour, minute and second. and the following aliases may be used:

• second — s sec secs seconds
• minute — m min mins minutes
• hour — h hr hrs hours
• day — d days
• week — w wk weeks
• month — M mon mons months
• year — y yr yrs years

a duration can also be specified using named parameters:

my $d = Badger::Duration->new(
    minutes => 4,
    seconds => 20,
);

or by reference to a hash array:

my $d = Badger::Duration->new({
    minutes => 4,
    seconds => 20,
});

and if that's your thing, you can also pass it as an explicit duration option instead:

my $d = Badger::Duration->new(
    duration => {
        minutes => 4,
        seconds => 20,
    }
);

in all cases, any of the valid aliases for durations may be used, e.g.

my $d = Badger::Duration->new(
    h => 1,
    m => 4,
    s => 20,
);

🍓 duration()

returns a reference to a hash array holding the canonical values of the duration.

my $d = Badger::Duration->new(
    duration => '4 hours 20 minutes'
);
my $h = $d->duration;
print $h->{ hour   };     # 4
print $h->{ minute };     # 20

🧚 seconds()

returns the total number of seconds for the duration. the whole thing. every last second. obsessed.

my $d = Badger::Duration->new(
    duration => '4 hours 20 minutes'
);
print $d->seconds;      # 15600

⭐ compare($that)

this method is defined to enable the functionality provided by the Badger::Comparable base class. so you can compare durations like it's nothing:

use Badger::Duration 'Duration';

my $d1 = Duration('4 hours 20 minutes');
my $d2 = Duration('270 minutes');

if ($d1 < $d2) {
    # ...do something...
}

🌸 text()

returns a canonical text representation of the duration.

use Badger::Duration 'Duration';
my $d1 = Duration('4 hrs 20 mins');
print $d1->text;            # 4 hours 20 minutes

note that the units get pluralised appropriately. e.g.

1 hour 1 minute 1 second
2 hours 2 minutes 2 seconds

this method is bound to the auto-stringification operation, which is a fancy way of saying it gets called automatically when you simply print a Badger::Duration object. so:

print $d1;                  # 4 hours 20 minutes

slay. it just knows. 💅

---

🔥 INTERNAL METHODS 🔥

(these are the behind-the-scenes girlies, iykyk)

💀 init($config)

object initialisation method, called automatically by the new() constructor method inherited from the Badger::Base base class.

🙈 parse_text($text)

internal method to parse a text string and return a hash reference of canonical values.

💜 parse_hash($hash)

internal method to parse a hash reference and return another hash reference of canonical values (e.g. after mapping aliases to canonical names).

⭐ count_seconds($hash)

counts the total number of seconds in a duration passed by reference to a hash array.

---

🫶 AUTHOR 🫶

Andy Wardley <http://wardley.org> — the legend themselves.

---

🌈 COPYRIGHT 🌈

Copyright (C) 2013 Andy Wardley. All Rights Reserved.

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page bestie, go forth and parse your durations 💖 — this was perl v5.36.0, dated 2023-08-28, signing off from Badger::Duration(3pm) 🎀✨🦋