/****************************************************************************
*                                                                           *
*   DTTOX.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_DTTOX

    DTTOX

    Purpose: Converts date/time values to X values.

    Syntax:  DTTOX(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 X values.

    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: dttox(w1, w2, w3)

             W1 contains the input data.

             W2 contains a date series.

             W3 contains a time series

             W4 returns the X Values {0, 5, 9} 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: xtodt(w1, {0, 5, 9});table
             W3: dttox(w1, w2)

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

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

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


/* convert date/time values to X valuess */
dttox(series, date = getdate(), time = gettime(13), timezone = "")
{
        local is_scalar, is_string, tstamp, idx;

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

        if (not(isarray(date) || isstring(date)))
        {
                error(sprintf("%s - date values required", __FUNC__));
        }

        is_scalar = isscalar(date);

        /* get  input args */
        (date, time, timezone, is_string) = utc_parse_args(date, time, timezone, TRUE, FALSE);

        /* convert to timestamps */
        tstamp = dt2timestamp(date, time, timezone);

        /* offset by series start date/time */
        tstamp -= dt2timestamp(getdate(series), gettime(series, 13));

        if (is_scalar)
        {
                tstamp = castreal(tstamp);
        }
        else
        {
                setvunits(tstamp, gethunits(series));
        }

        return(tstamp);
}