/*****************************************************************************
*                                                                            *
*   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)

             (date, time, y) = GETDT(series, utc)

             series - An interval or XY series. If not specified, defaults
                      to the current date and time.

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

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

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

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

    Example:
             W1: getdt()

             Returns a 1x2 series with the current date and time.

    Example:
             W1: getdt(1)

             Returns a 1x2 series with the current date and time in UTC.

    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: {ymd2date(1999, 1, 1), ymd2date(1999, 1, 10), ymd2date(1999, 4, 2)}
             W2: {hms2time(12, 0, 0), hms2time(14, 0, 0), hms2time(9, 35, 0)}
             W3: {1, 2, .5};setvunits("V")
             W4: xydt(w1, w2, w3)
             W5: getdt(w4)

             Same as above except the input dates are given in YMD format
             and the input times are given in HMS format.

    Example:
             W1: {ymd2date(1999, 1, 1), ymd2date(1999, 1, 10), ymd2date(1999, 4, 2)}
             W2: {hms2time(12, 0, 0), hms2time(14, 0, 0), hms2time(9, 35, 0)}
             W3: {1, 2, .5};setvunits("V")
             W4: xydt(w1, w2, w3)
             W5: getdt(w4, 1)

             Same as above except 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
             Hms2date
             Julstr
             Todstr
             Julymd
             Xy
             Xydt
             Ymd2date
             Ymdhms2dt
#endif

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


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

        /* parse args */
        (s, utc, dt_mode) = getdt_parse_args(argc, s, utc, dt_mode);

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

        /* iterate */
        (dval, tval) = getdt_process(s, utc, dt_mode);

        /* for multi-column date/time result */
        itemprocess(dval, 0);
        itemprocess(tval, 0);

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

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

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

                return(dt);
        }
}



getdt_parse_args(nargs, s, utc, dt_mode)
{
        if (nargs < 3)
        {
                if (nargs < 2)
                {
                        if (nargs < 1)
                        {
                                s = {1};
                        }

                        if (isscalar(s))
                        {
                                utc = s;
                                s = {1};
                        }
                }

                if (isscalar(s))
                {
                        dt_mode = utc;
                        utc = s;
                        s = {1};
                }
        }

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

        return(s, utc, dt_mode);
}


getdt_process(s, utc, dt_mode)
{
        /* time values with msec */
        dt = xvals(s, 1, dt_mode);

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

                dt += delta_t;
        }

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

        /* starting date */
        date = (utc) ? getutcdate(s) : getdate(s);
        dval = days + julstr(date);
        setmatrix(dval, 0);
        setvunits(dval, "Date");

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

        return(dval, tval);
}


/* 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);
}