/*****************************************************************************
*                                                                            *
*   TIME2HMS.SPL Copyright (C) 2024 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Converts series of time values to hours, minutes, seconds   *
*                                                                            *
*   Revisions:    2 Dec 2024  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_TIME2HMS

    TIME2HMS

    Purpose: Converts series of time values to hours, minutes and seconds.

    Syntax:  TIME2HMS(time)

             (hours, minutes, seconds) = TIME2HMS(time)

              times   - A scalar or series, the time (TOD) values.


    Returns: An Nx3 array of time of hours, minutes and seconds values.

             (hours, minutes, seconds) = TIME2HMS(time) returns the hours,
             minutes and seconds components in separate variables.

    Example:
             W1: time2hms(43200)

             W1 == {{12, 0, 0}}, a 1x3 series representing 12 hours, 0
             minutes and 0 seconds.

    Example:
             W2: time2hms(todstr("12:00:00"))

             Same as above, except the time value is entered as a string
             to the TODSTR function.

    Example:
             (h, m, s) = time2hms(todstr("12:00:00"))

             Same as above, except the time components are returned in three
             separate series variables.

             h == {12}
             m == {0}
             s == {0}

    Example:
             W1: hms2time({10, 12, 14}, {30, 40, 50}, {1, 2, 3})
             W2: time2hms(w1)

             W1 contains the time values:

                10:30:01
                12:40:02
                14:50:03

             W2 converts the time values in W1 to individual time components
             replicating the input values of W1.

             W2 == {{10, 30, 1},
                    {12, 40, 2},
                    {14, 50, 3}}

    Remarks:
             TIME2HMS creates a time component series by converting individual
             time of days values to hour, minutes and seconds values.

             A time of day or TOD value is the number of seconds since
             midnight.

             See HMS2TIME to create time of days values from hours, minutes
             and seconds values.
             
    See Also:
             Date2ymd
             Hms2time
             Strtod
             Strtodmsec
#endif


/* convert TOD time to hours, minutes, seconds series */
time2hms(time)
{
        local h, m, s, hms, nidx;

        if (argc == 0)
        {
                /* current time string */
                time = gettime(13);
        }

        if (isstring(time))
        {
                if (istimestr(time))
                {
                        time = todmsecstr(time);
                }
                else
                {
                        error(sprintf("%s - unrecognized time '%s'", __FUNC__, time));
                }
        }

        /* force series */
        time = {time};

        /* find negative values */
        nidx = find(time < 0);

        time = abs(time);

        /* conversion */
        h = int(time / 3600);
        s = time - h * 3600;

        m = int(s / 60);

        s -= m * 60;

        setvunits(h, "Hours", -1);
        setvunits(m, "Minutes", -1);
        setvunits(s, "Seconds", -1);

        h[nidx] *= -1;
        m[nidx] *= -1;
        s[nidx] *= -1;
        
        if (outargc > 1)
        {
                return(h, m, s);
        }
        else
        {
                hms = ravel(h, m, s);

                /* tabular view */
                settable(hms);

                return(hms);
        }
}