/ 
DateTimeX-Subspan-Weekly-0.04
/ DateTimeX::Subspan::Weekly

NAME

DateTimeX::Subspan::Weekly - Determine whether event falls within weekly recurring range

SYNOPSIS

use DateTimeX::Subspan::Weekly qw( in_range );

$rv = in_range( {
    starting_date   => $starting_date,  # Hash ref
    range           => $range_ref,      # Hash ref
    target          => $dt,             # DateTime object
} );

DESCRIPTION

Suppose that a 'week' can begin at an arbitrarily chosen day of the week and time of day. Suppose further that that week can be divided into two subspans: one in which an event is permitted to occur, and the other in which the event is not permitted to occur.

DateTimeX::Subspan::Weekly provides functions to determine a particular date falls in the permitted range or not.

SUBROUTINES

DateTimeX::Subspan::Weekly currently exports one subroutine on request.

in_range()

  • Purpose

    Determine whether or not a given date falls within the permitted subspan of a 'week' beginning at a given date within a normal week.

  • Arguments

    Takes a single hash reference with 3 required elements:

    $rv = in_range( {
    starting_date   =>
        { day => 6, hour => 0, minute => 0, second => 0 },
    range           =>
        { days => 5, hours => 20, minutes => 0, seconds => 0 },
    target          => DateTime->new(
        year   => 2010,
        month  => 1,
        day    => 1,
        hour   => 12,
        minute => 36,
        second => 47,
    ),
} );

    • starting_date

      Hash reference with elements keyed as day, hour, minute and second. These elements describe the date in the normal DateTime week (i.e., a 'week' where Monday is 1 and Sunday is 7) at which the 'permitted subspan' begins. In the example above, the permitted subspan begins Friday at 0000 hours.

    • range

      Hash reference with elements keyed as days, hours, minutes and seconds. These elements describe the duration of the permitted subspan, beginning at the starting_date. In the example above, the permitted subspan lasts for 5 days and 20 hours, i.e., until the following Wednesday at 2000 hours.

    • target

      DateTime object representing the date and time being tested to determine whether it is in the permitted range or not. If not provided, will default to DateTime-gtnow(), the equivalent of localtime. In the example above, January 1, 2010, 12::36::47 is being tested to determine whether it falls in the period beginning at starting_date and lasting for range.

  • Return Value

    Returns true value if date falls within permitted range. Returns false if date does not fall within permitted range.

$rv = in_range( { starting_date => $starting_date, range => $range_ref, target => $dt, } );

BUGS AND LIMITATIONS

This is very much alpha code; the interface may change at any time. In particular, the interface may change to an object-oriented one to become more consistent with the rest of the DateTime ecosphere.

Not yet tested for daylight-savings-time boundaries, leap years, etc.

SUPPORT

Bugs: http://rt.cpan.org. General support: email to author at address below.

AUTHOR

James E Keenan
CPAN ID: jkeenan
jkeenan@cpan.org
http://search.cpan.org/~jkeenan/

COPYRIGHT

Copyright 2010 James E Keenan.

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.

PREREQUISITES

Requires the DateTime and DateTime-set distributions from CPAN.