FUNCTION test_format_hms, str

; Description: This function checks that the string "str" is of the format "HH:MM:SS.SSS",
;              representing hours (HH), minutes (MM) and seconds (SS.SSS), where the 
;              precision on the seconds can extend to any number of decimal places. If 
;              "str" is of the correct format, then the function returns a value of "1".
;              If "str" is not of the correct format, then the function returns a value
;              of "0". Note that this function removes any white space from "str" before 
;              format testing.
;
; Input Parameters:
;
;   str - STRING - The string to be tested for the format "HH:MM:SS.SSS". Any white space 
;                  in this string is removed before format testing. Note that a string of 
;                  the format "HH:MM:SS." will be changed by the function to a string of 
;                  the format "HH:MM:SS".
;
; Return Value:
;
;   The function returns an INTEGER value set to "1" if "str" is of the format
;   "HH:MM:SS.SSS", and set to "0" if "str" is not of the format "HH:MM:SS.SSS".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   14/01/2009 - Module created (dmb)

;Check that "str" is a scalar string

;Remove any white space from "str"

;Check that "str" has at least 8 characters

;Decompose "str" into individual characters

;Check the values of the individual characters in "str", and check the hour, minute and
;second

;If "str" has 8 characters, then, by reaching this point, "str" has passed all the format 
;tests, and has the form "HH:MM:SS". In this case, the function will return a value of "1". 

;Perform another check on "str"

;If "str" has 9 characters, then, by reaching this point, "str" has passed all the format 
;tests, and has the form "HH:MM:SS.". In this case, the function will return a value of
;"1" and adjust the format of "str" to "HH:MM:SS".

;Perform the final checks on the decimal places of "str"

;By reaching this point, "str" has more than 9 characters, it has passed all the format 
;tests, and it has the format "HH:MM:SS.SSS". The function will now return a value of
;"1".