FUNCTION test_time_in_hours, time, status
; Description: This function checks that the input parameter "time" is either a number representing
; hours in the range "0.0 <= time < 24.0" ("time" may be of number type or string type
; in this case) or a valid time string of the format "HH:MM:SS.SSS". If "time" satisfies
; any of these conditions, then the function returns the input time as a double
; precision number in hours. If "time" does not satisfy any of these conditions, then
; the function returns the value of "-1.0". The input parameter "time" may be a scalar,
; vector, or array.
;
; Input Parameters:
;
; time - NUMBER/STRING SCALAR/VECTOR/ARRAY - A scalar/vector/array containing a set of numbers to
; be tested for representing a time in hours in the
; range "0.0 <= time < 24.0" ("time" may be of number
; type or string type in this case) or containing a set
; of strings to be tested for the format "HH:MM:SS.SSS".
; 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 number(s)/string(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 DOUBLE type variable, with the same dimensions as the input parameter
; "time". If an element of "time" is a number representing hours in the range "0.0 <= time < 24.0"
; ("time" may be of number type or string type in this case), then the corresponding element of
; the return variable is set to the double precision value of the current element of "time". If
; an element of "time" is a valid time string of the format "HH:MM:SS.SSS", then the corresponding
; element of the return variable is set to the value of the time string converted into a decimal
; number in hours. If an element of "time" does not satisfy either of the previously described
; cases, then the corresponding element of the return variable is set to the value "-1.0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 06/12/2011 - Module modified to accept scalar, vector, and array input (dmb).
; 15/01/2010 - Module created (dmb).
;Set the default output parameter values
;If "time" is of string type
;Attempt to convert the elements of "time" from the format "HH:MM:SS.SSS" to double precision numbers
;representing times in hours
;Determine which elements of "time" are not of the format "HH:MM:SS.SSS"
;If all of the elements of "time" are of the format "HH:MM:SS.SSS" (and have therefore been successfully
;converted to double precision numbers representing times in hours)
;Set "status" to "1"
;Return the elements of "time" as double precision numbers representing times in hours
;Check which elements of "time" are strings that represent numbers
;If at least one of the elements of "time" is a string that represents a number
;Convert the elements of "time" that are strings representing numbers into double precision numbers
;Determine which elements of "time" that are strings representing numbers lie outside the range
;"0.0 <= time < 24.0", and set the corresponding elements in the return variable to "-1.0"
;Transfer the converted elements of "time" that were strings representing numbers to the return
;variable
;Set "status" to "1"
;Return the elements of "time" as double precision numbers with those elements that do not lie in the
;range "0.0 <= time < 24.0" set to the value "-1.0"
;If "time" contains numbers
;Convert the elements of "time" to double precision numbers
;Determine which elements of "time" lie outside the range "0.0 <= time < 24.0", and set the corresponding
;elements in the return variable to "-1.0"
;Set "status" to "1"
;Return the elements of "time" as double precision numbers with those elements that do not lie in the
;range "0.0 <= time < 24.0" set to the value "-1.0"
;Return the default value for the return variable since, by reaching this point, the input parameter "time"
;is not of string type and it does not contain numbers