/****************************************************************************
*                                                                           *
*   XTODT.SPL    Copyright 2026 (C) DSP Development Corporation             *
*                              All Rights Reserved                          *
*                                                                           *
*   Author:      Randy Race                                                 *
*                                                                           *
*   Synopsis:    Converts X values to date/time values                      *
*                                                                           *
*   Revisions:   22 Jan 2026     RRR     Creation                           *
*                                                                           *
****************************************************************************/


#if @HELP_XTODT

    XTODT

    Purpose: Converts X values to date and times values.

    Syntax:  XTODT(series, x)

                series - A series, the input series.

                     x - A series, the X values.
  
    Returns: A series of date time values.

    Example:
             W1: gnorm(10, 1);setdate(w0, "1-1-2030");settime(w0, "12:00:00")
             W2: getdt(w1)
             W3: xtodt(w1, xvals(w1)

             W2 returns the date/time values of W1.

             W3 returns the same values using the X values of W1.

    Example:
             W1: gnorm(10, 1);setdate(w0, "1-1-2030");settime(w0, "12:00:00")
             W2: xtodt(w1, {1, 5, 10})
             W3: dttox(w1, w2)

             W2 returns the date/time values of W1 using the X values
             {1, 5, 10}.

             W3 returns the X values {1, 5, 10} from the date/time values
             in W1.
 
    Remarks:
             XTODT converts the xvalues of an input series to the
             equivalent date/time values based on the start date and start
             time of the series.

             See DTTOX to convert date/time values of a series to X values.
             
    See Also:
             DT2IDX
             DT2UNIX
             DT2YMDHMS
             DTTOX
             GETDT
             IDXTOX
             XTOIDX
#endif


/* convert X values to date time */
ITERATE xtodt(series, dt, utc = 0)
{
        local delta_t, days, date, dval, tval;

        if (utc)
        {
                /* utc time offset */
                delta_t = todmsecstr(getutctime(series, -1)) - todmsecstr(gettime(series, -1));

                dt += delta_t;
        }

        /* day overflow */
        days = int(dt / 86400);

        /* starting date */
        date = (utc) ? getutcdate(series) : getdate(series);
        dval = days + julstr(date);
        setmatrix(dval, 0);
        setvunits(dval, "Date");

        /* time values */
        tval = dt - days * 86400;

        /* add start time */
        tval += todmsecstr(gettime(series, 13));

        setmatrix(tval, 0);
        setvunits(tval, "Real Time");

        if (outargc > 1)
        {
                return(dval, tval);
        }
        else
        {
                return(ravel(dval, tval));
        }
}