README

Interval

This library provides some tools to handle intervals. For instance, you can compute the union or intersection of two intervals.

Use cases

• Availabilities calculation.
• Scheduling/calendar/planning.
• Mathematics interval computation with open/closed boundaries
• etc

Features

• It computes some operations between two intervals: union, intersection and exclusion.
• It computes some operations between two sets of intervals: exclusion for now.
• It handles several types of boundaries : float, \DateTime and integer.
• It handles infinity type as boundary.
• Ability to combine infinity with \DateTime and other types.
• filter, sort, map.
• Immutability.
• Chain operations.

Quality

• Code coverage
• Mutation test : Code coverage more than 90%
• Takes care of performance and memory usage
• PSR1/PSR2, Code Smell

Install

composer require kirouane/interval

Basic usage

Let's assume an interval [20, 40]. We instantiate a new Interval object .

$interval = new Interval(20, 40);// [20, 40];

or

$interval = Interval::create('[20,40]');// [20, 40];

We can do some operations like :

• Intersection :

echo $interval->intersect(new Interval(30, 60)); // [30, 40];

• Union :

echo $interval->union(new Interval(30, 60)); // {[20, 60]};

or

echo $interval->union(new Interval(60, 100)); // {[20, 40], [60, 100]};

• Exclusion :

echo $interval->exclude(new Interval(30, 60)); // {[20, 30[};

or

echo $interval->exclude(new Interval(30, 35)); // {[20, 30[, ]35, 40]};

We can compare two intervals as well:

• Overlapping test :

echo $interval->overlaps(new Interval(30, 60)); // true;

• Inclusion test :

echo $interval->includes(new Interval(30, 60)); // false;

Use DateTimeInterface as boundary

$interval = new Interval(new \DateTime('2016-01-01'), new \DateTime('2016-01-10'));
// [2016-01-01T00:00:00+01:00, 2016-01-10T00:00:00+01:00];

• Union :

echo $interval->union(Interval::create('[2016-01-10, 2016-01-15]')); 
// {[2016-01-01T00:00:00+01:00, 2016-01-15T00:00:00+01:00]};

Use Infinity as boundary

$interval = new Interval(-INF, INF);// ]-∞, +∞[;

• Exclusion :

echo $interval->exclude(Interval::create('[2016-01-10, 2016-01-15]')); 
// {]-∞, 2016-01-10T00:00:00+01:00[, ]2016-01-15T00:00:00+01:00, +∞[};

Operations on sets (arrays) of intervals

$intervals = Intervals::create(['[0,5]', '[8,12]']);// {[0, 5], [8, 12]};

• Exclusion :

echo $intervals->exclude(Intervals::create(['[3,10]'])); // {[0, 3[, ]10, 12]};

Chaining

$result = Interval
    ::create('[10, 20]')
    ->intersect(new Interval(11, 30))
    ->union(new Interval(15, INF))
    ->exclude(Intervals::create(['[18, 20]', '[25, 30]', '[32, 35]', '[12, 13]']))
    ->sort(function (Interval $first, Interval $second) {
        return $first->getStart()->getValue() <=> $second->getStart()->getValue();
    })
    ->map(function (Interval $interval) {
        return new Interval(
            $interval->getStart()->getValue() ** 2,
            $interval->getEnd()->getValue() ** 2
        );
    })
    ->filter(function (Interval $interval) {
        return $interval->getEnd()->getValue() > 170;
    }); 

// {[169, 324], [400, 625], [900, 1024], [1225, +∞[};
    
echo $result;    

Advanced usage

You can create intervals with open boundaries :

$result = Intervals
    ::create([']10, +INF['])
    ->exclude(Intervals::create([']18, 20]', ']25, 30[', '[32, 35]', ']12, 13]']));

// {]10, 12], ]13, 18], ]20, 25], [30, 32[, ]35, +∞[}

Contributing

You are very welcomed to contribute to this Library!

• Clone git clone https://github.com/Kirouane/interval.git

• Install composer install or make install (with docker and docker-compose)

• Test vendor/bin/phpunit

• Build vendor/bin/grumphp run