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".