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


#if @HELP_DTDURATION

    DTDURATION

    Purpose: Calculates the difference of date time series in seconds.

    Syntax:  DTDURATION(date1, time1, date2, time2)

               date1 - A series of Julian integer dates, the end date.

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

               date2 - Optional. A series of Julian integer dates,
                       the start date. Defaults to an empty series.

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


    Alternate Syntax:  DTDURATION(datetime1, datetime2)

                datetime1 - An array, the end date and time values in
                            adjacent columns.

                datetime2 - Optional. An array, the start date and time
                            values in adjacent columns. Defaults to an
                            empty array.

    Returns: A series, the elapsed duration in seconds.

             If only one date and time series or one composite date time
             series is specified, the durations are computed on the two
             point difference of each date time value.

    Example:
             W1: ymdhms2dt(2027, 1, 2, 12, 0, 0)
             W2: ymdhms2dt(2027, 3, 1, 12, 0, 0)
             W3: dtduration(w2, w1)
             W4: dtoffset(w1, seconds:w3)

             W1 contains the date time:

              1-02-2027 12:00:00

             W2 contains the date time:

              3-01-2027 12:00:00

             W3 computes the difference between the two date times in seconds.
             The duration is 5011200 seconds.

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

    Example:
             W1: ymdhms2dt(2028, 1, 2, 12, 0, 0)
             W2: ymdhms2dt(2028, 3, 1, 12, 0, 0)
             W3: dtduration(w2, w1)
             W4: dtoffset(w1, seconds:w3)

             Same as the first example except the end and start year
             is 2028, a leap year. The duration is 5097600 seconds. The
             duration has increased by 86400 seconds from 5011200 seconds
             to 5097600 because of the leap year.

    Example:
             W1: ymdhms2dt(2027, 1, 2, 12, 0, 0)
             W2: ymdhms2dt(2027, 3, 1, 12, 0, 0)
             W3: dtduration(w1, w2)
             W4: dtoffset(w2, seconds:w3)

             Same as the first example above except the start and end date
             times are swapped. The result is a negative duration of
             -5011200 seconds.

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

    Example:
             W1: gnorm(10, hours2seconds(2) + minutes2seconds(10) + 13.5)
             W2: getdt(w1)
             W3: dtduration(w2)
             W4: w3;setvunits("Real Time")

             W1 contains 10 random samples with a time spacing of 7813.5
             seconds or 2 hours 10 minutes and 13.5 seconds between samples.

             W2 computes the date time values for each sample in W1.

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

             W4 displays the durations in W3 in wall clock time. The values
             conform to the time spacing of W1.

    Remarks:
             DTDURATION computes the difference between two date time series
             with the result in seconds.

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

             A date time duration is measured in seconds.

             A date time period is measured in years, months, days, hours,
             minutes and seconds.

             See DTPERIOD to compute the time difference in years, months,
             days, hours, minutes and seconds.

    See Also:
             DATEDURATION
             DATEPERIOD
             DTDIFF
             DTOFFSET
             DTPERIOD
             TIMEDURATION
             TIMEPERIOD
             YMDHMS2DT
#endif


/* difference between date/time values in seconds */
dtduration(d1, t1, d2, t2)
{
        local ts, usediff, dateonly, timeonly;

        /* parse input args */
        (d1, t1, d2, t2, usediff, dateonly, timeonly) = dt_durper_parse_args(argc, d1, t1, d2, t2);

        if (usediff)
        {
                if (dateonly)
                {
                        /* date diff */
                        ts = dateduration(d1);
                }
                else if (timeonly)
                {
                        /* time diff */
                        ts = timeduration(d1);
                }
                else
                {
                        /* convert to internal timestamps */
                        ts = dt2timestamp(d1, t1);

                        if (not(isarray(ts)))
                        {
                                error(sprintf("%s - date time must be an array", __FUNC__));
                        }

                        /* diff on timestamps */
                        ts = diff(ts);
                }
        }
        else
        {
                if (dateonly)
                {
                        /* date duration */
                        ts = dateduration(d1, d2);
                }
                else if (timeonly)
                {
                        /* time duration */
                        ts = timeduration(t1, t2);
                }
                else
                {
                        /* difference bewteen series */
                        ts = dt2timestamp(d1, t1) - dt2timestamp(d2, t2);
                }
        }

        return(ts);
}