/*****************************************************************************
*                                                                            *
*   GETDT.SPL     Copyright (C) 2006-2024 DSP Development Corporation        *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns the date and time values of a series                *
*                                                                            *
*   Revisions:   13 Apr 2006  RRR  Creation                                  *
*                26 Oct 2007  RRR  tod fix for date values                   *
*                30 Aug 2024  RRR  UTC time and series items                 *
*                                                                            *
*****************************************************************************/

#if @HELP_GETDT

    GETDT

    Purpose: Returns the date and time values of a series.

    Syntax:  GETDT(series, utc, item)
             (date, time, y) = GETDT(series, utc, item)

             series - An interval or XY series.

                utc - Optional. An integer, the UTC date/time flag.

                       0: use local date/time (default)
                       1: use UTC date/time

               item - Optional. An integer, the series item.
                      Defauls to -1, the current focus.

    Returns: A 2 column table with the date and time values in
             each column.

             (date, time) = GETDT(series) returns the date and time
             values as separate series.

    Example:
             W1: {julstr("1-1-99"), julstr("1-10-99"), julstr("4-2-99")}
             W2: {todstr("12:00"), todstr("14:00"), todstr("9:35")}
             W3: {1, 2, .5};setvunits("V")
             W4: xydt(w1, w2, w3)
             W5: getdt(w4)

             The table in W5 consists of the values:

             1-01-1999,  12:00:00.000
             1-10-1999,  14:00:00.000
             4-02-1999,  09:35:00.000

    Example:
             W1: {julstr("1-1-99"), julstr("1-10-99"), julstr("4-2-99")}
             W2: {todstr("12:00"), todstr("14:00"), todstr("9:35")}
             W3: {1, 2, .5};setvunits("V")
             W4: xydt(w1, w2, w3)
             W5: getdt(w4, 1)

             Same as above except given the input local date/time values,
             the returned date/time values are in UTC time.

    Remarks:
             GETDT breaks out the date and time values from any series.

             The series date and time values are always saved in local
             date/time. If UTC is 1, the returned date/time values are
             in UTC date/time.

             The plot style is set to table view.

             See DTXY to return the date, time and Y values from a series.

             See XYDT to produce an XY series from separate date, time and
             y value series.

    See Also:
             Dtxy
             Julstr
             Todstr
             Julymd
             Xy
             Xydt
#endif

static dt_time = "";
static dt_date = "";

/* get the Date and Time values from a series */
ITERATE getdt2(s, utc = 0, item = -1, dt_mode = 4)
{
        local dt, dval, tval, time, date, delta_t;

        if (argc < 1 || not(isarray(s))) error(sprintf("%s - input series required"));

        if (length(s) == 0)
        {
                return({});
        }

        if (iswindow(s))
        {
                item = (item < 0) ? getfocus(s) : item;
        }
        else
        {
                item = 1;
        }

        /* normalize dt format */
        dt_time = setconfig("dt_time_format", 0);
        dt_date = setconfig("dt_date_format", 0);

        /* time values with msec */
        dt = xvals(s, item, dt_mode);
        
        setmatrix(dt, 0);

        if (utc)
        {
                /* utc time offset */
                delta_t = todmsecstr(getutctime(s, -1, item)) - todmsecstr(gettime(s, -1, item));

                dt += delta_t;
        }

        /* day overflow */
        days = int(dt / 86400);

        /* starting date */
        date = (utc) ? getutcdate(s, -1, item) : getdate(s, -1, item);
        dval = days + julstr(date);

        setmatrix(dval, 0);
        setvunits(dval, "Date");

        /* time values */
        tval = dt - days * 86400;
        setvunits(tval, "Real Time");

        setconfig("dt_time_format", dt_time);
        dt_time = "";

        setconfig("dt_date_format", dt_date);
        dt_date = "";

        if (outargc > 1)
        {
                return(dval, tval);
        }
        else
        {
                dt = ravel(dval, tval);
                setplotstyle(dt, 4);
                return(dt);
        }
}


/* error handler */
getdt_error(errnum, errmes)
{
        if (not(isstring(dt_time)))
        {
                setconfig("dt_time_format", dt_time);
                dt_time = "";
        }

        if (not(isstring(dt_date)))
        {
                setconfig("dt_date_format", dt_date);
                dt_date = "";
        }

        error(errmes);
}