marsapp\helper\timeperiod\TimePeriodHelper

Complexity

Total Complexity

75

Size/Duplication

Total Lines	511
Duplicated Lines	0 %

Importance

Changes	2
Bugs	1	Features	0

18 Methods

Rating	Name	Duplication	Size	Complexity
A	sort()	0	3	1
A	cut()	0	3	1
C	intersect()	0	44	12
A	filter()	0	3	1
A	greaterThan()	0	27	6
A	fill()	0	3	1
A	extend()	0	3	1
A	shorten()	0	3	1
A	format()	0	3	1
A	time()	0	3	1
A	union()	0	26	5
A	dataSortOut()	0	8	4
A	gap()	0	3	1
C	isOverlap()	0	36	12
A	validate()	0	3	1
A	lessThan()	0	27	6
B	contact()	0	32	7
C	diff()	0	48	13

<?php

namespace marsapp\helper\timeperiod;

use marsapp\helper\timeperiod\classes\Base;
use marsapp\helper\timeperiod\classes\DataProcess;

/**
 * Time Period Helper
 * 
 * Note:
 * 1. Format: $timePeriods = [[$startDatetime1, $endDatetime1], [$startDatetime2, $endDatetime2], ...];
 * - $Datetime = Y-m-d H:i:s ; Y-m-d H:i:00 ; Y-m-d H:00:00 ;
 * 2. If it is hour/minute/second, the end point is usually not included, for example, 8 o'clock to 9 o'clock is 1 hour.
 * - ●=====○
 * 3. If it is a day/month/year, it usually includes an end point, for example, January to March is 3 months.
 * - ●=====●
 * 4. When processing, assume that the $timePeriods format is correct. If necessary, you need to call the verification function to verify the data.
 * 5. Ensure performance by keeping the $timePeriods format correct:
 * - a. When getting the raw $timePeriods, sort out it by format(), filter(), union().
 * - b. Handle $timePeriods using only the functions provided by TimePeriodHelper (Will not break the format, sort)
 * - c. When you achieve the two operations described above, you can turn off auto sort out (TimePeriodHelper::setSortOut(false)) to improve performance.
 * 
 * @version 0.5.3
 * @author Mars Hung <tfaredxj@gmail.com>
 * @see https://github.com/marshung24/TimePeriodHelper
 */
class TimePeriodHelper extends Base
{

    /**
     * ************************************************
     * ************** Operation Function **************
     * ************************************************
     */

    /**
     * Sort time periods (Order by ASC)
     * 
     * 1. When sorting, sort the start time first, if the start time is the same, then sort the end time
     * 2. Sort Priority: Start Time => End Time
     * 
     * @param array $timePeriods
     * @return array
     */
    public static function sort(array $timePeriods)
    {
        return DataProcess::sort($timePeriods);
    }

    /**
     * Union one or more time periods
     * 
     * 1. Sort and merge one or more time periods with contacts
     * 2. TimePeriodHelper::union($timePeriods1, $timePeriods2, $timePeriods3, ......);
     * 
     * @param array $timePeriods
     * @return array
     */
    public static function union()
    {
        $opt = [];

        // Combine and sort
        $merge = call_user_func_array('array_merge', func_get_args());
        $merge = DataProcess::sort($merge);

        if (empty($merge)) {
            return $opt;
        }

        $tmp = array_shift($merge);
        foreach ($merge as $k => $tp) {
            if ($tp[0] > $tmp[1]) {
                // Got it, and set next.
                $opt[] = $tmp;
                $tmp = $tp;
            } elseif ($tp[1] > $tmp[1]) {
                // Extend end time
                $tmp[1] = $tp[1];
            }
        }
        $opt[] = $tmp;

        return $opt;
    }

    /**
     * Computes the difference of time periods
     * 
     * 1. Compares $timePeriods1 against $timePeriods2 and returns the values in $timePeriods1 that are not present in $timePeriods2.
     * 2. e.g. TimePeriodHelper::diff($timePeriods1, $timePeriods2);
     * 3. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods1
     * @param array $timePeriods2
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function diff(array $timePeriods1, array $timePeriods2, $sortOut = 'default')
    {
        /*** Arguments prepare ***/
        // Subject or pattern is empty, do nothing
        if (empty($timePeriods1) || empty($timePeriods2)) {
            return $timePeriods1;
        }

        // Data sorting out
        self::dataSortOut($sortOut, $timePeriods1, $timePeriods2);

        $opt = [];
        foreach ($timePeriods1 as $k1 => $ori) {
            foreach ($timePeriods2 as $ko => $sub) {
                if ($sub[1] <= $ori[0]) {
                    // No overlap && Passed: --sub0--sub1--ori0--ori1--
                    unset($timePeriods2[$ko]);
                    continue;
                } elseif ($ori[1] <= $sub[0]) {
                    // No overlap: --ori0--ori1--sub0--sub1--
                    continue;
                } elseif ($sub[0] <= $ori[0] && $ori[1] <= $sub[1]) {
                    // Subtract all: --sub0--ori0--ori1--sub1--
                    $ori = [];
                    break;
                } elseif ($ori[0] < $sub[0] && $sub[1] < $ori[1]) {
                    // Delete internal: --ori0--sub0--sub1--ori1--
                    $opt[] = [$ori[0], $sub[0]];
                    $ori = [$sub[1], $ori[1]];
                    //} elseif ($sub[0] <= $ori[0] && $sub[1] <= $ori[1]) { // Complete condition
                } elseif ($sub[0] <= $ori[0]) { // Equivalent condition
                    // Delete overlap: --sub0--ori0--sub1--ori1--
                    $ori = [$sub[1], $ori[1]];
                    //} elseif ($ori[0] <= $sub[0] && $ori[1] <= $sub[1]) { // Complete condition
                    //} elseif ($ori[1] <= $sub[1]) { // Equivalent condition
                } else { // Equivalent condition
                    // Delete overlap: --ori0--sub0--ori1--sub1--
                    $ori = [$ori[0], $sub[0]];
                }
            }

            // All No overlap
            if (!empty($ori)) {
                $opt[] = $ori;
            }
        }

        return $opt;
    }

    /**
     * Computes the intersection of time periods
     * 
     * 1. e.g. TimePeriodHelper::intersect($timePeriods1, $timePeriods2);
     * 2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods1
     * @param array $timePeriods2
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function intersect(array $timePeriods1, array $timePeriods2, $sortOut = 'default')
    {
        // Subject or pattern is empty, do nothing
        if (empty($timePeriods1) || empty($timePeriods2)) {
            return [];
        }

        // Data sorting out
        self::dataSortOut($sortOut, $timePeriods1, $timePeriods2);

        $opt = [];
        foreach ($timePeriods1 as $k1 => $ori) {
            foreach ($timePeriods2 as $ko => $sub) {
                if ($sub[1] <= $ori[0]) {
                    // No overlap && Passed: --sub0--sub1--ori0--ori1--
                    unset($timePeriods2[$ko]);
                    continue;
                } elseif ($ori[1] <= $sub[0]) {
                    // No overlap: --ori0--ori1--sub0--sub1--
                    continue;
                } elseif ($sub[0] <= $ori[0] && $ori[1] <= $sub[1]) {
                    // Subtract all: --sub0--ori0--ori1--sub1--
                    $opt[] = [$ori[0], $ori[1]];
                    break;
                } elseif ($ori[0] < $sub[0] && $sub[1] < $ori[1]) {
                    // Delete internal: --ori0--sub0--sub1--ori1--
                    $opt[] = [$sub[0], $sub[1]];
                    $ori = [$sub[1], $ori[1]];
                    //} elseif ($sub[0] <= $ori[0] && $sub[1] <= $ori[1]) { // Complete condition
                } elseif ($sub[0] <= $ori[0]) { // Equivalent condition
                    // Delete overlap: --sub0--ori0--sub1--ori1--
                    $opt[] = [$ori[0], $sub[1]];
                    $ori = [$sub[1], $ori[1]];
                    //} elseif ($ori[0] <= $sub[0] && $ori[1] <= $sub[1]) { // Complete condition
                    //} elseif ($ori[1] <= $sub[1]) { // Equivalent condition
                } else { // Equivalent condition
                    // Delete overlap: --ori0--sub0--ori1--sub1--
                    $opt[] = [$sub[0], $ori[1]];
                    break;
                }
            }
        }

        return $opt;
    }

    /**
     * Time period is overlap
     * 
     * 1. Determine if there is overlap between the two time periods
     * 2. Only when there is no intersection, no data is needed.
     * 3. Logic is similar to intersect.
     *  
     * @param array $timePeriods1
     * @param array $timePeriods2
     * @return bool
     */
    public static function isOverlap(array $timePeriods1, array $timePeriods2)
    {
        // Subject or pattern is empty, do nothing
        if (empty($timePeriods1) || empty($timePeriods2)) {
            return false;
        }

        foreach ($timePeriods1 as $k1 => $ori) {
            foreach ($timePeriods2 as $ko => $sub) {
                if ($sub[1] <= $ori[0]) {
                    // No overlap && Passed: --sub0--sub1--ori0--ori1--
                    unset($timePeriods2[$ko]);
                    continue;
                } elseif ($ori[1] <= $sub[0]) {
                    // No overlap: --ori0--ori1--sub0--sub1--
                    continue;
                } elseif ($sub[0] <= $ori[0] && $ori[1] <= $sub[1]) {
                    // Subtract all: --sub0--ori0--ori1--sub1--
                    return true;
                } elseif ($ori[0] < $sub[0] && $sub[1] < $ori[1]) {
                    // Delete internal: --ori0--sub0--sub1--ori1--
                    return true;
                    //} elseif ($sub[0] <= $ori[0] && $sub[1] <= $ori[1]) { // Complete condition
                } elseif ($sub[0] <= $ori[0]) { // Equivalent condition
                    // Delete overlap: --sub0--ori0--sub1--ori1--
                    return true;
                    //} elseif ($ori[0] <= $sub[0] && $ori[1] <= $sub[1]) { // Complete condition
                    //} elseif ($ori[1] <= $sub[1]) { // Equivalent condition
                } else { // Equivalent condition
                    // Delete overlap: --ori0--sub0--ori1--sub1--
                    return true;
                }
            }
        }

        return false;
    }

    /**
     * The time period is in contact with the specified time (time period)
     * 
     * @param array $timePeriods
     * @param string $sDateTime
     * @param string $eDateTime
     * @param string $sortOut
     * @return array
     */
    public static function contact(array $timePeriods, $sDateTime, $eDateTime = null, $sortOut = 'default')
    {
        // Subject is empty, do nothing
        if (empty($timePeriods)) {
            return [];
        }

        // Data sorting out
        self::dataSortOut($sortOut, $timePeriods);
        // Set $eDateTime
        $eDateTime = $eDateTime ?: $sDateTime;
        $sTime = min($sDateTime, $eDateTime);
        $eTime = max($sDateTime, $eDateTime);

        // Get Contact time periods
        $opt = [];
        foreach ($timePeriods as $k => $tp) {
            if ($eTime <= $tp[0]) {
                // No overlap && Passed: --$sTime--$eTime--$tp0--$tp1--
                if ($sTime == $tp[0]) {
                    // But 
                    $opt[] = $tp;
                }
            } elseif ($tp[1] <= $sTime) {
                // No overlap: --$tp0--$tp1--$sTime--$eTime--
            } else {
                // Overlap
                $opt[] = $tp;
            }
        }

        return $opt;
    }

    /**
     * Time period greater than the specified time
     * 
     * @param array $timePeriods
     * @param string $refDatetime
     * @param string $intactTime
     * @param string $sortOut
     * @return array
     */
    public static function greaterThan(array $timePeriods, $refDatetime, $intactTime = true, $sortOut = 'default')
    {
        // Subject is empty, do nothing
        if (empty($timePeriods)) {
            return [];
        }

        // Data sorting out
        self::dataSortOut($sortOut, $timePeriods);

        // Get Contact time periods
        $opt = [];
        foreach ($timePeriods as $k => $tp) {
            if ($intactTime) {
                // Time period is intact
                if ($tp[0] >= $refDatetime) {
                    $opt[] = $tp;
                }
            } else {
                // Time period not intact
                if ($tp[1] > $refDatetime) {
                    $opt[] = $tp;
                }
            }
        }

        return $opt;
    }

    /**
     * Time period less than the specified time
     * 
     * @param array $timePeriods
     * @param string $refDatetime
     * @param string $intactTime
     * @param string $sortOut
     * @return array
     */
    public static function lessThan(array $timePeriods, $refDatetime, $intactTime = true, $sortOut = 'default')
    {
        // Subject is empty, do nothing
        if (empty($timePeriods)) {
            return [];
        }

        // Data sorting out
        self::dataSortOut($sortOut, $timePeriods);

        // Get Contact time periods
        $opt = [];
        foreach ($timePeriods as $k => $tp) {
            if ($intactTime) {
                // Time period is intact
                if ($tp[1] <= $refDatetime) {
                    $opt[] = $tp;
                }
            } else {
                // Time period not intact
                if ($tp[0] < $refDatetime) {
                    $opt[] = $tp;
                }
            }
        }

        return $opt;
    }

    /**
     * Fill time periods
     * 
     * Leaving only the first start time and the last end time
     * 
     * @param array $timePeriods
     * @return array
     */
    public static function fill(array $timePeriods)
    {
        return DataProcess::fill($timePeriods);
    }

    /**
     * Get gap time periods of multiple sets of time periods
     * 
     * 1. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function gap(array $timePeriods, $sortOut = 'default')
    {
        return DataProcess::gap($timePeriods, $sortOut);
    }

    /**
     * Calculation period total time
     *
     * 1. You can specify the smallest unit (from setUnit())
     * 2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 3. approximation: chop off
     *
     * @param array $timePeriods            
     * @param int $precision
     *            Optional decimal places for the decimal point
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return number
     */
    public static function time(array $timePeriods, $precision = 0, $sortOut = 'default')
    {
        return DataProcess::time($timePeriods, $precision, $sortOut);
    }

    /**
     * Cut the time period of the specified length of time
     *
     * 1. You can specify the smallest unit (from setUnit())
     * 2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods            
     * @param number $time
     *            Specified length of time
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function cut(array $timePeriods, $time, $sortOut = 'default')
    {
        return DataProcess::cut($timePeriods, $time, $sortOut);
    }

    /**
     * Increase the time period of the specified length of time after the last time period
     *
     * 1. You can specify the smallest unit (from setUnit())
     * 2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods            
     * @param number $time
     *            Specified length of time (default uint:second)
     * @param number $interval
     *            Interval with existing time period
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function extend(array $timePeriods, $time, $interval = 0, $sortOut = 'default')
    {
        return DataProcess::extend($timePeriods, $time, $interval, $sortOut);
    }

    /**
     * Shorten the specified length of time from behind
     *
     * 1. You can specify the smallest unit (from setUnit())
     * 2. Whether $timePeriods is sorted out will affect the correctness of the results. Please refer to Note 5. Ensure performance by keeping the $timePeriods format correct.
     * 
     * @param array $timePeriods            
     * @param number $time
     *            Specified length of time (default uint:second)
     * @param bool $crossperiod
     *            Whether to shorten across time
     * @param bool|string $sortOut Whether the input needs to be rearranged. Value: true, false, 'default'. If it is 'default', see getSortOut()
     * @return array
     */
    public static function shorten(array $timePeriods, $time, $crossperiod = true, $sortOut = 'default')
    {
        return DataProcess::shorten($timePeriods, $time, $crossperiod, $sortOut);
    }

    /**
     * Transform format
     * 
     * @param array $timePeriods
     * @param string $unit Time unit, if default,use class options setting
     * @return array
     */
    public static function format(array $timePeriods, $unit = 'default')
    {
        return DataProcess::format($timePeriods, $unit);
    }

    /**
     * Validate time period
     * 
     * Verify format, size, start/end time
     * 
     * @param mixed|array $timePeriods
     * @throws \Exception
     * @return bool
     */
    public static function validate($timePeriods)
    {
        return DataProcess::validate($timePeriods);
    }

    /**
     * Remove invalid time period
     * 
     * 1. Verify format, size, start/end time, and remove invalid.
     * 2. time carry problem processing, e.g. 2019-01-01 24:00:00 => 2019-01-02 00:00:00
     * 
     * @param mixed|array $timePeriods
     * @throws \Exception
     * @return array
     */
    public static function filter($timePeriods)
    {
        return DataProcess::filter($timePeriods);
    }


    /**
     * ********************************************
     * ************** Tools Function **************
     * ********************************************
     */

    /**
     * Data sorting out
     *
     * @param bool|string $sortOut
     * @param array $timePeriods1
     * @param array|null $timePeriods2
     * @return void
     */
    public static function dataSortOut(&$sortOut, &$timePeriods1, &$timePeriods2 = null)
    {
        // Data sorting out
        $sortOut = $sortOut === 'default' ? self::getSortOut() : !!$sortOut;
        if ($sortOut) {
            $timePeriods1 = self::union($timePeriods1);
            if (!is_null($timePeriods2)) {
                $timePeriods2 = self::union($timePeriods2);
            }
        }
    }
}