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 any of the 
;              substrings of the format "EN", "eN", "E+N", "E-N", "e+N", "e-N", "ENN", 
;              "eNN", "E+NN", "E-NN", "e+NN", "e-NN", "ENNN" or "eNNN", where "N" is 
;              a place holder for any numerical digit.
;                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 (dmb@ing.iac.es)
;
; History:
;
;   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

;Make a copy of "str"

;Decompose "str" into individual characters

;If the first character in "str" is "+" or "-"

  ;If "str" has 2 characters, then check that the last character is a numerical
  ;digit

  ;If "str" has at least 3 characters, then temporarily remove the sign character 
  ;from "str"

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

;If "str" does not have a decimal point

  ;If "str" has 2 characters, then check that they are all numerical digits

    ;For each character in "str"

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

  ;If "str" has 3 or more characters, then count and check the number of times that 
  ;the characters "E" or "e" appear

  ;If the characters "E" and "e" are not present in "str", then check that all 
  ;characters in "str" are numerical digits

    ;For each character in "str"

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

  ;Check that only one of the characters "E" and "e" is present in "str"

  ;Determine the position of the "E" or "e" character in "str"

  ;If the position of the "E" or "e" character is 2 positions from the end, then
  ;the format of "str" must end "EN" or "eN"

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

    ;Check that the last character is a numerical digit

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

  ;At this point, if "str" has only 3 characters, then it cannot be a number

  ;If the position of the "E" or "e" character is 3 positions from the end, then
  ;the format of "str" must end "E+N", "E-N", "e+N", "e-N", "ENN" or "eNN"

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

    ;Check that the character after the "E" or "e" character is either "+" or "-", 
    ;or a numerical digit

    ;Check that the last character is a numerical digit

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

  ;At this point, if "str" has only 4 characters, then it cannot be a number

  ;If the position of the "E" or "e" character is 4 positions from the end, then
  ;the format of "str" must end "E+NN", "E-NN", "e+NN", "e-NN", "ENNN" or "eNNN"

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

    ;Check that the character after the "E" or "e" character is either "+" or "-",
    ;or a numerical digit

    ;Check that the last two characters are numerical digits

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

  ;If the position of the "E" or "e" character is not 3 or 4 positions from the end,
  ;then "str" is not a number

;If "str" does have a decimal point, then determine its position

;If "str" has 2 or 3 characters, then check that they are all numerical digits or "."

  ;For each character in "str"

  ;If "str" starts with a decimal point, then include a zero at the beginning

  ;If "str" ends with 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 4 or more characters, then count and check the number of times that
;the characters "E" or "e" appear

;If the characters "E" and "e" are not present in "str", then check that all
;characters in "str" are numerical digits or "."

  ;For each character in "str"

  ;If "str" starts with a decimal point, then include a zero at the beginning

  ;If "str" ends with 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".

;Check that only one of the characters "E" and "e" is present in "str"

;Determine the position of the "E" or "e" character in "str"

;If the position of the "E" or "e" character is 2 positions from the end, then
;the format of "str" must end "EN" or "eN"

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

  ;Check that the last character is a numerical digit

  ;If "str" starts with a decimal point, then include a zero at the beginning

  ;If the decimal point in "str" is just before the "E" or "e" character, 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".

;At this point, if "str" has only 4 characters, then it cannot be a number

;If the position of the "E" or "e" character is 3 positions from the end, then
;the format of "str" must end "E+N", "E-N", "e+N", "e-N", "ENN" or "eNN"

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

  ;Check that the character after the "E" or "e" character is either "+" or "-",
  ;or a numerical digit

  ;Check that the last character is a numerical digit

  ;If "str" starts with a decimal point, then include a zero at the beginning

  ;If the decimal point in "str" is just before the "E" or "e" character, 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".

;At this point, if "str" has only 5 characters, then it cannot be a number

;If the position of the "E" or "e" character is 4 positions from the end, then
;the format of "str" must end "E+NN", "E-NN", "e+NN", "e-NN", "ENNN" or "eNNN"

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

  ;Check that the character after the "E" or "e" character is either "+" or "-",
  ;or a numerical digit

  ;Check that the last two characters are numerical digits

  ;If "str" starts with a decimal point, then include a zero at the beginning

  ;If the decimal point in "str" is just before the "E" or "e" character, 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".