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


#if @HELP_XTODSTR

    XTODSTR  

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

               s     - Optional. A series, the target series. Defaults to
                       the current series.
                
              "time" - A string, the target time.
                
              "date" - Optional. A string, the target date.
                

    Returns: A real, the corresponding X value for the given time/date
             value.

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

             x1 = xtodstr(w1, "12:00:00");idx1 = xtoidx(w1, x1);

             x2 = xtodstr(w1, "12:00:00", "1-2-2020");idx2 = xtoidx(w1, x2);

             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.

             x1 == 0.0, idx1 == 1 indicating time 12:00:00 on 1-01-2020 is
             sample number 1 with an x value of 0.0.

             x2 == 864000.0, idx2 == 8641 indicating time 12:00:00 on
             1-02-2020 is sample number 8641 with an x value of 86400.0.

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

             linedraw(w2, lred, castreal(xtodstr("13:00:00")), 0.0, xtodstr("13:00:00", "1/2/2020"), 0.0);

             W2 contains the same time series as above. A red line is drawn at
             a Y value of 0.0 ranging from 13:00:00 on 1-1-2020 to 13:00:00 on
             1-2-2020. The CASTREAL function is required to indicate the
             values from XTODSTR are real valued plot coordinates.

    Remarks:
             XTODSTR converts time values based on the input series or the
             current series of no input series is provided.

             If the series spans multiple days, specify the optional DATE
             value to indicate the day for the time value.

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

    See Also:
             Julstr
             Strjul
             Strtod
             Strxtod
             Todstr
#endif


/* convert time/date value to x value */
xtodstr(s, t, date)
{
        local dt, x;

        /* input args */
        (s, t, date) = xtodstr_parse_args(s, t, date);

        /* date offset */
        dt = julstr(date) - julstr(getdate(s));

        /* convert time/date to x */
        x = todmsecstr(t) - todmsecstr(gettime(s)) + dt * 86400.0;

        /* return as real */
        return(castreal(x));
}


/* parse input args */
xtodstr_parse_args(s, t, date)
{
        local s_arg, t_arg, d_arg;

        s_arg = t_arg = d_arg = {};

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

                if (isstring(t))
                {
                        t_arg = t;
                }

                if (isstring(date))
                {
                        d_arg = date;
                }
        }
        else if (isstring(s))
        {
                if (isstring(t))
                {
                        d_arg = t;
                }

                t_arg = s;
        }

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

        if (isempty(t_arg))
        {
                error("xtodstr - time string required");
        }

        if (isempty(d_arg))
        {
                d_arg = getdate(s_arg);
        }

        return(s_arg, t_arg, d_arg);
}