/*****************************************************************************
*                                                                            *
*   HMS2TIME.SPL Copyright (C) 2024 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Converts a series to time values                            *
*                                                                            *
*   Revisions:    2 Dec 2024  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_HMS2TIME

    HMS2TIME

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

    Syntax:  HMS2TIME(hours, minutes, seconds)

              hours   - A scalar or series, the hours values.

              minutes - A scalar or series, the minutes values.

              seconds - A scalar or series, the seconds values.


    Returns: A series or array of time of day values.

    Example:
             W1: hms2time(12, 0, 0)

             W1 contains the time 12:00:00 with the equivalent time of day
             value of 43200 seconds.

    Example:
             W1: {11, 12, 13}
             W2: {15, 30, 45}
             W3: {10, 20, 30}
             W4: hms2time(w1, w2, w3)

             W1 contains the hours values.

             W2 contains the minutes values.

             W3 contains the seconds values.

             W4 contains the time series:

                11:15:10
                12:30:20
                13:45:30

    Example:
             W1: hms2time(11..13, {15, 30, 45}, {10, 20, 30})

             Same as above except the hour, minutes and seconds values are
             entered directly as series.

             W1 contains the time series:

                11:15:10
                12:30:20
                13:45:30

    Example:
             W1: hms2time(11..13, {15, 30, 45}, {10, 20, 70})

             Same as above except the last seconds value of 70 causes the
             resulting minutes to rollover.

             W1 contains the time series:

                11:15:10
                12:30:20
                13:46:10

    Remarks:
             HMS2TIME creates a time series by combining individual hour,
             minutes and seconds values.

             Out of range minutes and seconds values are rolled over.

             A time of day or TOD value is the number of seconds since
             midnight.
             
    See Also:
             Time2hms
             Todstr
             Todmsecstr
             Ymd2date
             Ymdhms2dt
#endif


/* hours, minutes seconds to todmsec */
hms2time(hours = 0, minutes = 0, seconds = 0)
{
        local time = {}, msec;

        if (argc <= 1)
        {
                if (argc < 1)
                {
                        /* current date */
                        hours = gettime(13);
                }

                if (istimestr(hours))
                {
                        /* convert time string - force series */
                        time = {todmsecstr(hours)};
                }
                else if (isstring(hours))
                {
                        error(sprintf("%s - unrecognized time '%s'", __FUNC__, hours));
                }
        }

        if (isempty(time))
        {
                (hours, minutes, seconds) = d_or_t_2_parse_args(argc, hours, minutes, seconds);

                /* conversion */
                time = hours * 3600 + minutes * 60 + seconds;
        }

        /* Real Time if time has fractional part */
        msec = any((time - int(time)) % 1);

        setvunits(time, (msec ? "Real Time" : "Time"), -1);

        /* tabular view */
        settable(time);

        return(time);
}