/****************************************************************************
*                                                                           *
*   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, limit)

                series - A series, the input series.

                     x - A series, the X values.

                  limit - Optional integer, limit result to existing
                          indices range.

                           0: do not limit output
                           1: limit output to existing indices (default)
  
    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, x, limit = 1, utc = 0, forceidx = 1)
{
        local delta_t, dt;

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

        if (not(isarray(series)))
        {
                error(sprintf("%s - input series required", __FUNC__));
        }

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

        /* starting date/time */
        dt = getstartdt(series);

        if (forceidx)
        {
                /* remap X to index values - possibly out of range */
                x = idxtox(series, xtoidx(series, x, limit));
        }

        /* shift by start dt by x seconds */
        dt = dtoffset(dt, seconds:x);

        if (isarray(x))
        {
                setcomment(dt, getcomment(x));
        }

        if (outargc > 1)
        {
                return(col(dt, 1), col(dt, 2));
        }
        else
        {
                return(dt);
        }
}