/****************************************************************************
*                                                                           *
*   DT2YMDHMS.SPL Copyright 2024 (C) DSP Development Corporation            *
*                                                                           *
*   Author:       Randy Race                                                *
*                                                                           *
*   Synopsis:     Converts date time to YMDHMS                              *
*                                                                           *
*   Revisions:    10 Nov 2024     RRR     Creation                          *
*                                                                           *
****************************************************************************/


#if @HELP_DT2YMDHMS

    DT2YMDHMS

    Purpose: Converts date time values to years, months, days, hours,
             minutes, seconds.

    Syntax:  DT2YMDHMS(date, time, "timezone")

             (yr, mo, dy, hr, mn, s) = DT2YMDHMS(date, time, "timezone")

                    date - Optional. A string or series of Julian integer
                           dates, the input date. Defaults to the current
                           date.

                    time - Optional. A string or series of time of day values,
                           the input time. Defaults to the current time.

              "timezone" - Optional. A string, the local time zone. Defaults
                           to the current time zone. If specified, the
                           resulting timestamps are based on UTC time.
    
    Alternate Syntax:  DT2YMDHMS(datetime, "timezone")

             (yr, mo, dy, hr, mn, s) = DT2YMDHMS(datetime, "timezone")

                datetime - An array, the date and time values in adjacent
                           columns.

              "timezone" - Optional. A string, the local time zone. Defaults
                           to the current time zone. If specified, the
                           timestamps are based on UTC time.

    Returns: A N x 6 series of years, months, days, hours, minutes, seconds.

             (yr, mo, dy, hr, mn, s) = DT2YMDHMS(date, time, "timezone")

             returns the values in separate variables.

    Example:
             W1: dt2ymdhms()

             W1 contains a 1x6 series with the current date as separate year,
             month, day, hours, minutes, seconds values.

    Example:
             W2: dt2ymdhms("1-1-2030", "12:30:00")

             W2 contains a 1x6 series with the following values:

             {{2030, 1, 1, 12, 30, 0}}

    Example:
             (yr, mo, dy, hr, mn, s) = dt2ymdhms("1-1-2030", "12:30:00");
             W3: ravel(yr, mo, dy, hr, mn, s)

             Same as above except the years, months, days, hours, minutes and
             seconds components are returned to separate variables. The
             variables are combine to produce the series:

             {{2030, 1, 1, 12, 30, 0}}

    Example:
             W1: {{2030,1,1,0,0,0},{2031,2,2,2,4,6},{2032,3,3,8,10,12}}
             W2: ymdhms2dt(w1)
             W3: dt2ymdhms(w2)
             W4: all(w1 == w3)

             W1 contains a series of raw years, months, days, hours, minutes
             and seconds values.

             W2 converts the raw years, months, days, hours, minutes and
             and seconds values in W1 to a date time series. W2 contains
             the date times:

              1-01-2030 0:00:00
              2-02-2030 2:04:06
              3-03-2032 8:10:12

             W3 converts the date time values in W2 back into years, months,
             days, hours, minutes and seconds values.

             W4 compares the original years, months, days, hours, minutes and
             seconds values in W1 to the recovered values in W3. The result
             is all ones, indicating the two series are equal.

    Remarks:
             DT2YMDHMS converts a date time series to a series of years,
             months, days, hours, minutes and seconds.

             See YMDHMS2DT to convert a series of years, months, days, hours,
             minutes, seconds to a date time series.

    See Also:
             DATE2DT
             DT2DATE
             DT2TIMESTAMP
             DT2UNIX
             GETDT
             YMD2DATE
             YMDHMS2DT
#endif


/* convert date and time to years, months, days, hours, minutes, seconds */
dt2ymdhms(date = getdate(), time = gettime(13), timezone = "")
{
        local yr, mo, dy, hr, mn, ss, ymdhms, frac, hidx;

        (date, time, timezone) = utc_parse_args(date, time, timezone);

        if (strlen(timezone) > 0)
        {
                /* convert to UTC */
                (date, time) = local2utc(date, time, timezone);
        }

        /* convert julians */
        (yr, mo, dy) = date2ymd(date);

        /* total time, include fractional julians since noon */
        time  = time + (date - int(date)) * 86400;

        /* convert TODs */
        (hr, mn, ss) = time2hms(time);

        /* hour overflow */
        hidx = find(hr >= 24);

        /* update days and hours */
        if (length(hidx) > 0)
        {
                dy[hidx]++;
                hr[hidx] -= 24;
        }

        if (outargc > 1)
        {
                return(yr, mo, dy, hr, mn, ss);
        }
        else
        {
                ymdhms = ravel(yr, mo, dy, hr, mn, ss);

                settable(ymdhms);

                return(ymdhms);
        }
}