FUNCTION test_numstr_scalar, str
; Description: This function tests that the parameter "str" is a string that represents
; a number, with or without a decimal point and/or a plus or minus sign.
; The parameter "str" will also be considered to represent a number in the
; cases that it starts or ends with a decimal point, or 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 represents a number, then the function returns
; the string "str", with any leading or trailing white space removed, and
; any other required neatening of the string format. If "str" is not a
; string that represents a number, then the function returns the string
; 'ERROR'.
;
; Input Parameters:
;
; str - ANY - The parameter to be tested for a string that represents a number. Leading
; or trailing white space is ignored.
;
; Return Value:
;
; The function returns a STRING value. In the case that "str" is a string that represents
; a number, then the return value is the same as "str" but with any leading or trailing
; white space removed. Furthermore, if the input string "str" starts with a decimal
; point, then the return value will be modified by the function to include a zero at
; the beginning. Similarly, if the input string "str" ends with a decimal point, then
; the return value will be modified by the function to exclude the decimal point.
; In the case that "str" is not a string that represents a number, then the return
; value is the string 'ERROR'.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 17/04/2010 - Module created (dmb).
;Check that "str" is a scalar string
;Remove any leading or trailing 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 the formatted string.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;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 the formatted string.
;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 the formatted string.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;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 the formatted string.
;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 the formatted string.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;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 the formatted string.
;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 the formatted string.