/*****************************************************************************
*                                                                            *
*   STRXTOD.SPL Copyright (C) 2020 DSP Development Corporation               *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:     Randy Race                                                   *
*                                                                            *
*   Synopsis:   Converts an X value to time/date                             *
*                                                                            *
*   Revisions:  18 Aug 2020  RRR  Creation                                   *
*                                                                            *
*****************************************************************************/


#if @HELP_STRXTOD

    STRXTOD  

    Purpose: Converts an X value to a time/date value.
                                                                        
    Syntax:  STRXTOD(s, x)

             (time, date) = STRXTOD(s, x)

               s - Optional. A series, the target series. Defaults to
                   the current series.
                
               x - A real. The X value to convert.
                

    Returns: A string, the corresponding time value for the given X value.

             (time, date) = STRXTOD(x) returns both the time and date
             strings for the given X value.

    Example:
             W1: gsin(10000, 10, 1/100000);settime("12:00");setdate("1-1-2020");sethunits("Time")

             t1 = strxtod(w1, 0.0);

             t2 = strxtod(w1, idxtox(w1, 10000));

             W1 contains a sinusoidal time series where the time values range
             from 12:00:00 1/01/2020 to 15:46:30 1/02/2020.

             t1 == "12:00:00.000" indicating that X value 0.0 occurs at time
             12:00:00.

             t2 == "15:46:30.000" indicating that the X value at index 10000
             occurs at time 15:46:30.

    Example:
             W2: gsin(10000, 10, 1/100000);settime("12:00");setdate("1-1-2020");sethunits("Time")

             (t1, d1) = strxtod(w2, 0.0);

             (t2, d2) = strxtod(w2, idxtox(w2, 10000));

             W2 contains the same sinusoidal time series as above.

             t1 == "12:00:00.000", d1 == "1-01-2020" indicating that X value
             0.0 occurs at time 12:00:00 on 1-01-2020.

             t2 == "13:46:30.000", d2 == "1-02-2020" indicating that the X
             value at index 10000 occurs at time 13:46:30 on 1-02-2020.

    Remarks:
             STRXTOD converts an X value in seconds based on the input
             series or the current series of no input series is
             provided.

             See XTODSTR to convert a time/date value into an X value.

    See Also:
             Julstr
             Strjul
             Strtod
             Todstr
             Xtodstr
#endif


/* convert x value into a time/date value */
strxtod(s, x)
{
        local time, date;

        /* input args */
        (s, x) = strxtod_parse_args(s, x);

        /* starting time */
        x += todmsecstr(gettime(s));

        time = strtodmsec(x);

        if (outargc > 1)
        {
                /* fraction of days */
                date = x / 86400.0;

                /* increment by integer days */
                date = julstr(getdate(s)) + int(date);
                date = strjul(date);

                /* time/date */
                return(time, date);
        }
        else
        {
                return(time);
        }
}


/* parse input args */
strxtod_parse_args(s, x)
{
        local s_arg, x_arg;

        s_arg = x_arg = {};

        if (isarray(s))
        {
                s_arg = refseries(s);

                if (isscalar(x))
                {
                        x_arg = x;
                }
        }
        else if (isscalar(s))
        {
                x_arg = s;

                s = refseries(w0);
        }

        if (isempty(s_arg))
        {
                s_arg = refseries(w0);
        }

        if (isempty(x_arg))
        {
                error("strxtod - input X value required");
        }

        return(s_arg, x_arg);
}