FUNCTION hours2hms, hour, ndp, status, NO_PAR_CHECK = no_par_check
; Description: This function converts a time in hours "hour" to a string of the format
; "HH:MM:SS.SSS" representing a valid time in hours (HH, "00" to "23"), minutes
; (MM, "00" to "59"), and seconds (SS.SSS, "00.000" to "59.999") with a precision of
; "ndp" decimal points on the seconds. The input parameter "hour" may be a scalar,
; vector, or array.
;
; Input Parameters:
;
; hour - BYTE/INTEGER/LONG/FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array containing
; a set of times in hours.
; ndp - INTEGER/LONG - The number of decimal points to return on the seconds in the formatted
; time string(s). If this parameter is negative or greater than "16",
; then the function will return three decimal places on the seconds in
; the formatted time string(s).
; status - ANY - A variable which will be used to contain the output status of the function on
; returning (see output parameters below).
;
; Output Parameters:
;
; status - INTEGER - If the function successfully processed the input time(s), then "status"
; is returned with a value of "1", otherwise it is returned with a value of
; "0".
;
; Return Value:
;
; The function returns a STRING type variable, with the same dimensions as the input parameter
; "hour", where each element represents a time in the format "HH:MM:SS.SSS" and in the range 0
; to 24 hours. Where elements of "hour" are not valid times in the range 0 to 24 hours, the
; string 'ERROR' is returned.
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the function will not perform
; parameter checking on the input parameters, reducing function overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 01/01/2010 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "hour" and "ndp" are of the correct number types
;If "ndp" is outside the acceptable range, then use the default value of "3" to set the format
;of the time strings
;Convert the elements of "hour" to double precision numbers
;Determine which of the elements of "hour" are in the range 0 to 24 hours, taking into account
;the rounding introduced by limiting the number of decimal places on the seconds
;If none of the elements of "hour" are in the range 0 to 24 hours
;Set "status" to "1"
;Return the results of the time conversion of the elements of "hour"
;If all of the elements of "hour" are in the range 0 to 24 hours
;Determine the number of hours, minutes, and seconds for each time
;Enforce the format "SS.SSS" for the strings representing the seconds for each time
;Convert the times in hours stored in "hour" into time strings of the format "HH:MM:SS.SSS"
;If not all of the elements of "hour" are in the range 0 to 24 hours
;Prepare the set of output time strings
;Extract the elements of "hour" that are in the range 0 to 24 hours
;Determine the number of hours, minutes, and seconds for each time
;Enforce the format "SS.SSS" for the strings representing the seconds for each time
;Convert the times in hours stored in "hour" into time strings of the format "HH:MM:SS.SSS"
;Set "status" to "1"
;Return the results of the time conversion of the elements of "hour"