FUNCTION test_num_str, str

; Description: This function tests that the parameter "str" is a string that contains 
;              a number, with or without a decimal point and/or a plus or minus sign. 
;              If "str" starts with a decimal point, then "str" will be updated to 
;              include a zero at the beginning. If "str" ends with a decimal point, 
;              then "str" will be updated to exclude the decimal point. The parameter 
;              "str" will also be considered a number if it ends with a substring of
;              any of the formats "EN...N", "eN...N", "E+N...N", E-N...N", "e+N...N"
;              or "e-N...N", where "N...N" is a place holder for any set of numerical
;              digits of any length.
;                If "str" is a string that contains a number, then the function 
;              returns a value of "1". If "str" is not a string that contains a number, 
;              then the function returns a value of "0". Note that this function 
;              removes any white space from "str" before format testing.
;
; Input Parameters:
;
;   str - ANY - The parameter to be tested for a string containing a number. Any white 
;               space in this string is removed before format testing.
;
; Return Value:
;
;   The function returns an INTEGER value set to "1" if "str" is a string that contains 
;   a number, and set to "0" if "str" is not a string that contains a number.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   17/04/2009 - Module fully rewritten to be more logical and flexible (dmb).
;   15/01/2009 - Module created (dmb)

;Check that "str" is a scalar string

;Remove any white space from "str"

;Check that "str" has at least 1 character

;If "str" has 1 character, then check that it is a numerical digit

;Decompose "str" into individual characters

;Count and check the number of decimal points in "str"

;Count and check the number of "E" and "e" characters in "str"

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;If "str" has no decimal points and no "E" or "e" characters, then check that all characters
;are numerical digits, taking into account that the first character may be a "+" or "-"
;character

  ;Check that the first character is a numerical digit or a "+" or "-" character

  ;Check that the remaining characters are numerical digits only

  ;By reaching this point, "str" has passed all the relevant format tests. The 
  ;function will now return a value of "1".

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;If "str" has a decimal point but no "E" or "e" characters

  ;Determine if the first character is a "+" or "-" character

  ;If the first character is a "+" or "-" character

    ;Check that "str" does not consist only of a "+" or "-" character and a decimal point

    ;Check that the remaining characters are numerical digits or a decimal point

    ;If the second character is a decimal point, then insert a zero before the decimal point

    ;If the last character is a decimal point, then remove the decimal point

    ;By reaching this point, "str" has passed all the relevant format tests. The
    ;function will now return a value of "1".

  ;If the first character is not a "+" or "-" character, then check that the characters
  ;in "str" are numerical digits or a decimal point

  ;If the first character is a decimal point, then insert a zero before the decimal point

  ;If the last character is a decimal point, then remove the decimal point

  ;By reaching this point, "str" has passed all the relevant format tests. The
  ;function will now return a value of "1".

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;If "str" has no decimal point but has one of the characters "E" or "e"

  ;Check that "str" has at least 3 characters

  ;Determine if the first character is a "+" or "-" character

  ;If the first character is a "+" or "-" character

    ;Check that "str" has at least 4 characters

    ;Check that the "E" or "e" character is not the first character after the "+" 
    ;or "-" character, and that it is not the last character

    ;Check that the characters between the "+" or "-" character and the "E" or "e" 
    ;character are numerical digits only

    ;Check that the characters after the "E" or "e" character form a number without
    ;a decimal point

    ;By reaching this point, "str" has passed all the relevant format tests. The
    ;function will now return a value of "1".

  ;If the first character is not a "+" or "-" character, then check that the "E" or "e" 
  ;character is not the first or last character

  ;Check that the characters before the "E" or "e" character are numerical digits only

  ;Check that the characters after the "E" or "e" character form a number without
  ;a decimal point

  ;By reaching this point, "str" has passed all the relevant format tests. The 
  ;function will now return a value of "1".

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;If "str" has a decimal point and one of the characters "E" or "e", then check
;that "str" has at least 4 characters

;Determine if the first character is a "+" or "-" character

;If the first character is a "+" or "-" character

  ;Check that "str" has at least 5 characters

  ;Check that the "E" or "e" character is not the first or second character after 
  ;the "+" or "-" character, and that it is not the last character

  ;Check that the characters between the "+" or "-" character and the "E" or "e"
  ;character are numerical digits or a decimal point

  ;Check that the characters after the "E" or "e" character form a number without
  ;a decimal point

  ;If the second character is a decimal point, then insert a zero before the decimal point

  ;If the last character before the "E" or "e" character is a decimal point, then remove 
  ;the decimal point

  ;By reaching this point, "str" has passed all the relevant format tests. The
  ;function will now return a value of "1".

;If the first character is not a "+" or "-" character, then check that the "E" or "e"
;character is not the first, second or last character

;Check that the characters before the "E" or "e" character are numerical digits or a 
;decimal point

;Check that the characters after the "E" or "e" character form a number without
;a decimal point

;If the first character is a decimal point, then insert a zero before the decimal point

;If the last character before the "E" or "e" character is a decimal point, then remove
;the decimal point

;By reaching this point, "str" has passed all the relevant format tests. The
;function will now return a value of "1".