/****************************************************************************
*                                                                           *
*   TIMEPERIOD.SPL Copyright 2024 (C) DSP Development Corporation           *
*                                                                           *
*   Author:        Randy Race                                               *
*                                                                           *
*   Synopsis:      Calculates time difference in HMS                        *
*                                                                           *
*   Revisions:     10 Nov 2024     RRR     Creation                         *
*                                                                           *
****************************************************************************/


#if @HELP_TIMEPERIOD

    TIMEPERIOD

    Purpose: Calculates the difference of time series in hours, minutes and
             seconds.

    Syntax:  TIMEPERIOD(time1, time2)

             (h, m, s) = TIMEPERIOD(time1, time2)

                    time1 - A series of time of day values, the end time.

                    time2 - Optional. A series of time of day values,
                            the start time. Defaults to an empty series.


    Returns: The elapsed period as an N x 3 series of hours, minutes and
             seconds.

             (h, m, s) = TIMEPERIOD(time1, time2)

             returns the values in separate variables.
             
             If only one time series is specified, the periods are computed
             on the two point difference of each time value.

    Example:
             W1: hms2time(10, 11, 12)
             W2: hms2time(20, 30, 40)
             W3: timeperiod(w2, w1)
             W4: timeoffset(w1, w3)

             W1 contains the time:

              10:11:12

             W2 contains the time:

              20:30:40

             W3 computes difference between the two time series in hours,
             minutes and seconds. The period is 10 hours, 19 minutes and
             28 seconds.

             W4 recovers the end time in W2 by adding the offset in W3 to
             the start time in W1.

    Example:
             W1: hms2time(10, 11, 12)
             W2: hms2time(20, 30, 40)
             W3: timeperiod(w1, w2)
             W4: timeoffset(w2, w3)

             Same as the first example except the start and end times
             are swapped. The result is a negative period, -10 hours,
             -19 minutes and -28 seconds.

             W4 recovers the earlier end time in W1 time by adding the
             negative offset in W3 to the later start time in W2.

    Example:
             W1: gnorm(10, 1.005)
             W2: col(getdt(w1), 2)
             W3: timeperiod(w2)
             W4: hms2time(w3)

             W1 contains 10 random samples with a time spacing of 1.005
             seconds between samples.

             W2 computes the time values for each sample in W1.

             Because only one time series input was given, W3 computes
             the two point time difference between subsequent samples of W2.
             The result is 0 hours, 0 minutes and 1.005 seconds for each
             sample, equal to the original sample spacing of the series
             in W1.

             W4 displays the time differences contained in W3 in wall clock
             format.

    Remarks:
             TIMEPERIOD computes the difference between two time series
             with the result in periods of hours, minutes and seconds.

             If only one time series is provided, the two point period
             difference between subsequent time values is computed.

             A time period is measured in hours, minutes and seconds.

             A time duration is measured in seconds.

             See TIMEDURATION to compute the time difference in seconds.

    See Also:
             DTDIFF
             DTDURATION
             DT2UNIX
             YMDHMS2DT
#endif


/* time difference in hours, minutes, seconds */
timeperiod(t1, t2)
{
        local h, m, s, delta_t, hms, usediff = FALSE;

        if (argc < 2)
        {
                if (argc < 1)
                {
                        error(sprintf("%s - input time series required", __FUNC__));
                }

                usediff = TRUE;
        }

        if (usediff)
        {
                /* two point difference */
                delta_t = diff({t1});
        }
        else
        {
                /* difference between */
                delta_t = {t1} - {t2};
        }

        /* conversion from seconds */
        (h, m, s) = time2hms(delta_t);

        if (outargc > 1)
        {
                return(h, m, s);
        }
        else
        {
                hms = ravel(h, m, s);

                settable(hms);

                return(hms);
        }
}