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


#if @HELP_DTTOIDX

    DTTOIDX

    Purpose: Converts date/time values to indices.

    Syntax:  DTTOIDX(series, date, time, "timezone")

                  series - A series, the input series.

                    date - A series, the date value.

                            time - A series, the time values.

              "timezone" - Optional. A string, the local timezone.
                           Defaults to the current time zone. If specified,
                           the resulting timestamps are based on UTC time.
                           
    Returns: A series of integer indices.

    Example:
             W1: gnorm(10, 1);setdate(w0, "1/1/2030");settime(w0, "12:00:00")
             W2: {julstr("1/1/2030"), julstr("1/1/2030"), julstr("1/1/2030")};setvunits("Date");table 
             W3: {todstr("12:00:00"), todstr("12:00:04"), todstr("12:00:09")};setvunits("Time");table
             W4: dttoidx(w1, w2, w3)

             W1 contains the input data.

             W2 contains a date series.

             W3 contains a time series

             W4 returns the indices {1, 5, 10} of W1 using the date values
             in W2 and the time values in W3

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

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

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

             See IDXTODT to convert indices to date/time values.
             
    See Also:
             DTTOIDX
             DT2UNIX
             DT2YMDHMS
             GETDT
             IDXTODT
             IDXTOX
             XTOIDX
#endif


/* convert date/time values to indices */
dttoidx(series, date = getdate(), time = "", limit = 1)
{
        local x, idx;

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

        if (argc < 2)
        {
                error(sprintf("%s - date values required", __FUNC__));
        }

        if (argc == 3)
        {
                if (isarray(date) && isscalar(time))
                {
                        limit = time;
                        time  = "";
                }
        }

        x = dttox(series, date, time);

        idx = xtoidx(series, x, limit);

        return(idx);
}