Business::Hours(3pm)

📦
version 0.13 · 7 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Business::Hours — calculate business hours in a time period 🕘🕕

🌸 SYNOPSIS 🌸

  use Business::Hours;
  my $hours = Business::Hours->new();

  # Get a Set::IntSpan of all the business hours in the next week.
  # use the default business hours of 9am to 6pm localtime.
  $hours->for_timespan( Start => time(), End => time()+(86400*7) );

🦋 DESCRIPTION 🦋

okay so bestie, this module is a simple little tool for calculating business hours inside a time period. 💅

And like — over time, additional functionality will be added to make it easy to calculate the number of business hours between arbitrary dates. That's the plan, that's the vibe, that's the roadmap. ✨

💜 USAGE 💜

🎀 new

Creates a brand new Business::Hours object. Takes no arguments. That's it, that's the whole thing, she's low maintenance. 💖

🎀 business_hours HASH

Gets / sets the business hours for this object. It takes a hash (and like, NOT a hash reference, bestie, I'm serious 🙈) of this form:

    my %hours = (
        0 => { Name     => 'Sunday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },

        1 => { Name     => 'Monday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },
        ....

        6 => { Name     => 'Saturday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },
    );

Start and End times are of the form HH:MM. Valid times go from 00:00 to 23:59. If your hours are from 9am to 6pm, use Start => '9:00', End => '18:00'. A given day MUST have a start and end time OR may declare both Start and End to be undef, if there are no valid hours on that day. No half-measures, okay? Pick a lane. 🫶

You can use the array Breaks to mark interruptions between Start/End (for instance, lunch hour 🍓). It's an array of periods, each with a Start and End time:

    my %hours = (
        0 => { Name     => 'Sunday',
               Start    => 'HH:MM',
               End      => 'HH:MM',
               Breaks  => [
                             { Start    => 'HH:MM',
                             End      => 'HH:MM' },
                             { Start    => 'HH:MM',
                             End      => 'HH:MM' },
                           ],

        1 => { Name     => 'Monday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },
        ....

        6 => { Name     => 'Saturday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },
    );
👑 Note that the ending time is really "what is the first minute we're closed." If you specify an End of 18:00, that means that at 6pm, you are closed. The last business second was 17:59:59. The way that 18:00 is literally the closed door and not the last open moment… iconic but also a lil sneaky, so watch out. 💀

As well, you can pass information about holidays using the key 'holidays' and an array reference value, for example:

    $hours->business_hours(
        0 => { Name     => 'Sunday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },
        ....
        6 => { Name     => 'Saturday',
               Start    => 'HH:MM',
               End      => 'HH:MM' },

        holidays => [qw(01-01 12-25 2009-05-08)],
    );

Read more about holidays specification below in holidays. ⬇️

🎀 preprocess_business_hours

Checks and transforms business hours data. No need to call it. Like, genuinely, you don't have to, she handles herself. ✨

🎀 holidays ARRAY

Gets / sets holidays for this object. Takes an array where each element is ether 'MM-DD' or 'YYYY-MM-DD'. 🗓️

Specification with year defined may be required when a holiday matches Sunday or Saturday. In many countries days are shifted in such case. fr fr, that's just how it works there.

Holidays can be set via the business_hours method as well, so you can use this feature without changing your code. 🫶

🎀 for_timespan HASH

Takes a hash with the following parameters:

  • Start — the start of the period in question, in seconds since the epoch ⏰
  • End — the end of the period in question, in seconds since the epoch ⏰

Returns a Set::IntSpan of business hours for this period of time. 🎁

🎀 between START, END

Returns the number of business seconds between START and END. Both START and END should be specified in seconds since the epoch.

Returns -1 if START or END are outside the calculated business hours. 😭

🎀 first_after START

Returns START if START is within business hours. Otherwise, returns the next business second after START. START should be specified in seconds since the epoch.

Returns -1 if it can't find any business hours within thirty days. 💀

🎀 add_seconds START, SECONDS

Returns a time SECONDS business seconds after START. START should be specified in seconds since the epoch.

Returns -1 if it can't find any business hours within thirty days. 💀

🙈 BUGS 🙈

Yes, most likely. 😭 Please report them to bug-business-hours@rt.cpan.org. Do it, bestie, the maintainers wanna hear from you. 💌

👑 AUTHOR 👑

Jesse Vincent, jesse@cpan.org

Copyright 2003-2008 Best Practical Solutions, LLC.

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

The full text of the license can be found in the LICENSE file included with this module.

and that's the whole page, bestie — this doc came from the perl v5.36.0 toolchain, dated 2022-12-04, in the User Contributed Perl Documentation collection. go forth and calculate your business hours responsibly. slay. 💅✨🦋

📦 where this page comes from