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


#if @HELP_TIMEDURATION

    TIMEDURATION

    Purpose: Calculates the difference of time series in seconds.

    Syntax:  TIMEDURATION(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: A series, the elapsed time duration in seconds.
             
             If only one time series is specified, the durations are computed
             on the two point difference of each time value.

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

             W1 contains the time:

              10:11:12

             W2 contains the time:

              20:30:40

             W3 computes difference between the two time series in seconds.
             The duration is 37168 seconds.

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

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

             Same as the first example except the start and end times are
             swapped. The result is a negative duration of -37168 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: timeduration(w2)
             W4: w3;setvunits("Real Time")

             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 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:
             TIMEDURATION computes the difference between two time series
             with the result a duration in seconds.

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

             A time duration is measured in seconds.

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

             See TIMEPERIOD to compute the time difference in hours, minutes
             and seconds.

    See Also:
             DATEDURATION
             DATEPERIOD
             DTDIFF
             DTDURATION
             DTPERIOD
             HMS2TIME
             TIMEOFFSET
             TIMEPERIOD
#endif


/* time difference in seconds */
timeduration(t1, t2)
{
        local delta_t, 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};
        }

        setvunits(delta_t, "s");

        settable(delta_t);

        return(delta_t);
}