ESMF_UtilString2Int Function

  function ESMF_UtilString2Int(string, keywordEnforcer,  &
      specialStringList, specialValueList, rc)
! !RETURN VALUE:
    integer :: ESMF_UtilString2Int
! !ARGUMENTS:
    character(len=*), intent(in)            :: string
type(ESMF_KeywordEnforcer), optional:: keywordEnforcer ! must use keywords below
    character(len=*), intent(in),  optional :: specialStringList(:)
    integer,          intent(in),  optional :: specialValueList(:)
    integer,          intent(out), optional :: rc
! !DESCRIPTION:
!   Return the numerical integer value represented by the {\tt string}.
!   If {\tt string} matches a string in the optional {\tt specialStringList}, the
!   corresponding special value will be returned instead.
!
!   If special strings are to be taken into account, both 
!   {\tt specialStringList} and {\tt specialValueList} arguments must be
!   present and of same size.
!   
!   An error is returned, and return value set to 0, if {\tt string} is not
!   found in {\tt specialStringList}, and does not convert into an integer
!   value.
!
!   Leading and trailing blanks in {\tt string} are ignored when directly
!   converting into integers.
!
!   This procedure may fail when used in an expression in a {\tt write} statement
!   with some older, pre-Fortran 2003, compiler environments that do not support
!   re-entrant I/O calls.
!
!   The arguments are:
!   \begin{description}
!   \item[string]
!     The string to be converted
!   \item[{[specialStringList]}]
!     List of special strings.
!   \item[{[specialValueList]}]
!     List of values associated with special strings.
!   \item[{[rc]}]
!     Return code; equals {\tt ESMF\_SUCCESS} if there are no errors.
!   \end{description}
!
!EOPI
  !-----------------------------------------------------------------------------
    ! local variables
    logical                   :: ssL, svL
    integer                   :: i
    integer                   :: ioerr
    character(:), allocatable :: tempString
    
    if (present(rc)) rc = ESMF_SUCCESS
    
    ESMF_UtilString2Int = 0 ! initialize
    
    ! checking consistency of inputs provided
    ssL = present(specialStringList)
    svL = present(specialValueList)
    
    if (ssL.neqv.svL) then
      call ESMF_LogSetError(ESMF_RC_ARG_BAD, &
        msg="Both specialStringList and specialValueList must either be "// &
        "present or absent.", &
        line=__LINE__, &
        file=ESMF_FILENAME, &
        rcToReturn=rc)
      return ! bail out
    endif

    tempString = trim(adjustl(string))! remove leading and trailing white spaces

    if (ssL) then
      ! special strings and values present
      if (size(specialStringList) /= size(specialValueList)) then
        call ESMF_LogSetError(ESMF_RC_ARG_BAD, &
          msg="Both specialStringList and specialValueList must have "// &
          "the same number of elements.", &
          line=__LINE__, &
          file=ESMF_FILENAME, &
          rcToReturn=rc)
        return ! bail out
      endif
      do i=1, size(specialStringList)
        if (tempString==trim(specialStringList(i))) then
          ! found a matching special string
          ESMF_UtilString2Int = specialValueList(i)
          return ! successful early return
        endif
      enddo
    endif
    
    if (verify(tempString,"-+0123456789") == 0) then
      ! should convert to integer just fine
      read (tempString, "(i12)", iostat=ioerr) ESMF_UtilString2Int
      if (ioerr /= 0) then
        call ESMF_LogSetError(ESMF_RC_ARG_BAD, &
            msg="The string '"//tempString//"' could not be converted to integer.", &
            line=__LINE__, &
            file=ESMF_FILENAME, &
            rcToReturn=rc)
        return ! bail out
      end if
    else
      ! the string contains characters besides numbers
      call ESMF_LogSetError(ESMF_RC_ARG_BAD, &
        msg="The string '"//tempString//"' contains characters besides "// &
          "numbers, cannot convert to integer.", &
        line=__LINE__, &
        file=ESMF_FILENAME, &
        rcToReturn=rc)
      return ! bail out
    endif
    
  end function ESMF_UtilString2Int