dictionary.F90

Go to the documentation of this file.

module dictionary
 
  use iso_c_binding, only : c_int, c_float, c_double, c_bool
  use constants_and_conversions, only : itinyval, ftinyval, true, false
  use exceptions
  use logfiles
  use fstring
  use fstring_list
  use exceptions
  implicit none
 
  private
 
  type, public :: dict_entry_t
 
    character (len=:), allocatable            :: key
    character (len=:), allocatable            :: secondary_key
 
    type (fstring_list_t)                     :: sl
    type (dict_entry_t), pointer              :: previous   => null()
    type (dict_entry_t), pointer              :: next       => null()
 
  contains
 
    procedure   :: add_key_sub
    generic     :: add_key => add_key_sub
 
    procedure   :: add_string_sub
    procedure   :: add_integer_sub
    procedure   :: add_float_sub
    procedure   :: add_double_sub
    procedure   :: add_logical_sub
    generic     :: add_value  => add_string_sub,   &
                                 add_integer_sub,  &
                                 add_float_sub,    &
                                 add_double_sub,   &
                                 add_logical_sub
  end type dict_entry_t
 
 
  type, public :: dict_t
 
    type (dict_entry_t), pointer   :: first   => null()
    type (dict_entry_t), pointer   :: last    => null()
    type (dict_entry_t), pointer   :: current => null()
    integer (c_int)                :: count   = 0
 
  contains
 
    procedure, private   :: get_entry_by_key_fn
    procedure, private   :: get_entry_by_index_fn
    generic              :: get_entry => get_entry_by_key_fn,    &
                                         get_entry_by_index_fn
 
    procedure, private   :: get_next_entry_by_key_fn
    procedure, private   :: get_next_entry_fn
    generic              :: get_next_entry => get_next_entry_by_key_fn, &
                                              get_next_entry_fn
 
    procedure, private   :: add_entry_to_dict_sub
    generic              :: add_entry => add_entry_to_dict_sub
 
    procedure, private   :: key_name_already_in_use_fn
    generic              :: key_already_in_use => key_name_already_in_use_fn
 
    procedure            :: find_dict_entry_fn
    generic              :: find_dict_entry => find_dict_entry_fn
 
    procedure, private   :: delete_entry_by_key_sub
    generic              :: delete_entry => delete_entry_by_key_sub
 
    procedure, private   :: print_all_dictionary_entries_sub
    generic              :: print_all => print_all_dictionary_entries_sub
 
    procedure, private   :: grep_dictionary_key_names_fn
    generic              :: grep_keys => grep_dictionary_key_names_fn
 
    procedure, public    :: get_value => get_value_as_string_sub
 
    procedure, private   :: get_values_as_int_sub
    procedure, private   :: get_values_as_float_sub
    procedure, private   :: get_values_as_logical_sub
    procedure, private   :: get_values_as_string_list_sub
    procedure, private   :: get_values_as_int_given_list_of_keys_sub
    procedure, private   :: get_values_as_float_given_list_of_keys_sub
    procedure, private   :: get_values_as_logical_given_list_of_keys_sub
    procedure, private   :: get_values_as_string_list_given_list_of_keys_sub
    generic              :: get_values => get_values_as_int_sub,                          &
                                          get_values_as_float_sub,                        &
                                          get_values_as_logical_sub,                      &
                                          get_values_as_string_list_sub,                  &
                                          get_values_as_int_given_list_of_keys_sub,       &
                                          get_values_as_float_given_list_of_keys_sub,     &
                                          get_values_as_logical_given_list_of_keys_sub,   &
                                          get_values_as_string_list_given_list_of_keys_sub
 
  end type dict_t
 
  ! CF = "Control File"; this dictionary will be populated elsewhere with all of the
  !                      directives found in the SWB control file.
  type (dict_t), public                     :: cf_dict
  type (dict_entry_t), public, pointer      :: cf_entry
 
contains
 
 !!
 !! This section contains methods bound to the DICT_ENTRY_T class
 !!
 
 subroutine add_key_sub(this, sKey)
 
    class(dict_entry_t)            :: this
    character (len=*), intent(in)   :: sKey
 
     this%key = trim(skey)
 
  end subroutine add_key_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_string_sub(this, sValue)
 
    class(dict_entry_t)            :: this
    character (len=*), intent(in)   :: sValue
 
    call this%sl%append(svalue)
 
  end subroutine add_string_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_float_sub(this, fValue)
 
    class(dict_entry_t)             :: this
    real (c_float), intent(in)       :: fValue
 
    call this%sl%append( ascharacter( fvalue ) )
 
  end subroutine add_float_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_integer_sub(this, iValue)
 
    class(dict_entry_t)               :: this
    integer (c_int), intent(in)        :: iValue
 
    call this%sl%append( ascharacter( ivalue ) )
 
  end subroutine add_integer_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_double_sub(this, dValue)
 
    class(dict_entry_t)               :: this
    real (c_double), intent(in)        :: dValue
 
    call this%sl%append( ascharacter( dvalue ) )
 
  end subroutine add_double_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_logical_sub(this, lValue)
 
    class(dict_entry_t)                :: this
    logical (c_bool), intent(in)   :: lValue
 
    call this%sl%append( ascharacter( lvalue ) )
 
  end subroutine add_logical_sub
 
!--------------------------------------------------------------------------------------------------
 
  !!
  !! The methods in the section below are bound to the DICT_T type, which is essentially a
  !! linked list of DICT_ENTRY_T objects
  !!
 
  function get_entry_by_key_fn(this, sKey)   result( pDict )
 
    class(dict_t)                :: this
    character (len=*), intent(in) :: skey
    type (dict_entry_t), pointer  :: pdict
 
    this%current => this%first
 
    do while ( associated( this%current ) )
 
      if ( this%current%key .strapprox. skey )  exit
 
      this%current => this%current%next
 
    enddo
 
    if (.not. associated( this%current ) )  &
      call warn( smessage="Failed to find a dictionary entry with a key value of "//dquote(skey),   &
                 iloglevel=log_debug,                                                               &
                 lecho=false )
 
    pdict => this%current
 
  end function get_entry_by_key_fn
 
!--------------------------------------------------------------------------------------------------
 
  function get_entry_by_index_fn(this, iIndex)   result( pDict )
 
    class(dict_t)                   :: this
    integer (c_int), intent(in)      :: iindex
    type (dict_entry_t), pointer     :: pdict
 
    ! [ LOCALS ]
    integer (c_int)  :: icurrentindex
 
    icurrentindex = 1
 
    this%current => this%first
 
    do
 
      if ( .not. associated( this%current ) ) exit
 
      if ( icurrentindex == iindex )  exit
 
      this%current => this%current%next
 
      icurrentindex = icurrentindex + 1
 
    enddo
 
    if (.not. associated( this%current ) )  &
      call warn( smessage="Failed to find a dictionary entry with a index value of "   &
        //ascharacter(iindex),                                                         &
                 iloglevel=log_debug,                                                  &
                 lecho=false )
 
    pdict => this%current
 
  end function get_entry_by_index_fn
 
!--------------------------------------------------------------------------------------------------
 
  function get_next_entry_by_key_fn(this, sKey)   result( pDict )
 
    class(dict_t)                :: this
    character (len=*), intent(in) :: skey
    type (dict_entry_t), pointer  :: pdict
 
    pdict => null()
 
    ! if "current" location is not null, it will point to the location of the
    ! last key value found. move forward by one before examining the next key...
    if (associated( this%current) ) pdict => this%current%next
 
    do while ( associated( pdict ) )
 
      if ( pdict%key .strequal. skey )  exit
 
      pdict => pdict%next
      this%current => pdict
 
    enddo
 
    if (.not. associated( pdict ) )  &
      call warn( smessage="Failed to find another dictionary entry with a key value of "//dquote(skey),   &
                 iloglevel=log_debug,                                                               &
                 lecho=false )
 
  end function get_next_entry_by_key_fn
 
!--------------------------------------------------------------------------------------------------
 
  function get_next_entry_fn(this)   result( pDict )
 
    class(dict_t)                :: this
    type (dict_entry_t), pointer  :: pdict
 
    pdict => null()
 
    ! if "current" location is not null, it will point to the location of the
    ! last key value found. move forward by one before examining the next key...
    if (associated( this%current) ) then
      pdict => this%current%next
      this%current => this%current%next
    endif
 
    if (.not. associated( pdict ) )  &
      call warn( smessage="Reached end of dictionary.",                    &
                 iloglevel=log_debug,                                      &
                 lecho=false )
 
  end function get_next_entry_fn
 
!--------------------------------------------------------------------------------------------------
 
  function grep_dictionary_key_names_fn(this, sKey)   result( slString )
 
    class(dict_t)                   :: this
    character (len=*), intent(in)    :: skey
    type (fstring_list_t)             :: slstring
 
    ! [ LOCALS ]
 
    this%current => this%first
 
    do while ( associated(this%current ) )
 
      if ( this%current%key .containssimilar. skey )         &
         call slstring%append(this%current%key)
 
      this%current => this%current%next
 
    enddo
 
    if ( slstring%get(1) == '<NA>' )            &
      call warn(smessage="Failed to find a dictionary entry associated with a key value of " &
        //dquote(skey)//".", smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false )
 
  end function grep_dictionary_key_names_fn
 
!--------------------------------------------------------------------------------------------------
 
function key_name_already_in_use_fn(this, sKey)   result( in_use )
 
  class(dict_t)                   :: this
  character (len=*), intent(in)    :: skey
  logical (c_bool)                 :: in_use
 
  ! [ LOCALS ]
  integer (c_int)             :: icount
 
  this%current => this%first
  icount = 0
 
  do while ( associated(this%current ) )
 
    !iIndex = index(string=this%current%key, substring=asUppercase(sKey) )
 
    !if ( iIndex > 0 ) iCount = iCount + 1
 
    if ( this%current%key .strapprox. skey )  icount = icount + 1
 
    this%current => this%current%next
 
  enddo
 
  if ( icount == 0 ) then
 
    in_use = false
 
  else
 
    in_use = true
 
  endif
 
end function key_name_already_in_use_fn
 
 
!--------------------------------------------------------------------------------------------------
 
function find_dict_entry_fn(this, sSearchKey)   result( pDict )
 
  class(dict_t)                   :: this
  character (len=*), intent(in)    :: ssearchkey
  type (dict_entry_t), pointer     :: pdict
 
  ! [ LOCALS ]
 
  pdict => null()
  this%current => this%first
 
  do while ( associated(this%current ) )
 
    !iIndex = index(string=this%current%key, substring=asUppercase(sSearchKey) )
 
    !if ( iIndex > 0 ) then
 
    if (this%current%key .strapprox. ssearchkey ) then
 
      pdict => this%current
      exit
 
    endif
 
    this%current => this%current%next
 
  enddo
 
end function find_dict_entry_fn
 
!--------------------------------------------------------------------------------------------------
 
  subroutine add_entry_to_dict_sub(this, dict_entry)
 
    class(dict_t)                :: this
    type (DICT_ENTRY_T), pointer  :: dict_entry
 
    type (DICT_ENTRY_T), pointer  :: temp_dict_entry
    integer (c_int)          :: iIndex
 
    temp_dict_entry => null()
 
    if ( associated(dict_entry) ) then
 
      temp_dict_entry => this%find_dict_entry( dict_entry%key )
 
      ! the dictionary already contains a dictionary entry with this
      ! key value; append the values to the existing entry
      if ( associated( temp_dict_entry ) ) then
 
        do iindex=1, dict_entry%sl%count
 
          call temp_dict_entry%sl%append( dict_entry%sl%get( iindex ) )
 
        enddo
 
        temp_dict_entry => null()
 
      else
 
        this%count = this%count + 1
 
        if ( associated( this%last) ) then
 
        ! dictionary has at least one entry
 
          dict_entry%previous  => this%last
          dict_entry%next      => null()
          this%last%next       => dict_entry
          this%last            => dict_entry
          this%current         => dict_entry
 
        else  ! this is the first dictionary entry
 
          this%first => dict_entry
          this%last  => dict_entry
          this%current => dict_entry
          dict_entry%previous => null()
          dict_entry%next     => null()
 
        endif
 
      endif
 
    else
 
      call warn( smessage="Internal programming error: dictionary entry is null",   &
          smodule=__file__, iline=__line__ )
 
    endif
 
  end subroutine add_entry_to_dict_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine delete_entry_by_key_sub(this, sKey)
 
    class(dict_t)                  :: this
    character (len=*), intent(in)   :: sKey
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    type (DICT_ENTRY_T), pointer   :: pTemp
 
    ptarget => this%get_entry(skey)
 
    if ( associated( ptarget ) ) then
 
      ! first remove object from linked list
      ptemp => ptarget%previous
 
      if (associated( ptemp) ) then
        ! if pTemp is unassociated, it means we are at the head of the list
        ptemp%next => ptarget%next
        ptarget%next%previous => ptemp
 
      else
 
        ptemp => ptarget%next
        this%first => ptemp
 
      endif
 
      ! set "current" pointer to entry that was just before the now-deleted entry
      this%current => ptemp
 
      call ptarget%sl%clear()
 
    endif
 
  end subroutine delete_entry_by_key_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_values_as_int_sub(this, sKey, iValues, is_fatal )
 
    class(dict_t)                                  :: this
    character (len=*)                               :: sKey
    integer (c_int), allocatable, intent(out)       :: iValues(:)
    logical (c_bool), optional                      :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    ptarget => this%get_entry(skey)
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key value of "//dquote(skey),                                  &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      ivalues = ptarget%sl%get_integer()
 
    else
 
      allocate(ivalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to iValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value of "//dquote(skey), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
      ivalues = itinyval
 
    endif
 
  end subroutine get_values_as_int_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_values_as_logical_sub(this, sKey, lValues, is_fatal)
 
    class(dict_t)                                   :: this
    character (len=*)                                :: sKey
    logical (c_bool), allocatable, intent(out)       :: lValues(:)
    logical (c_bool), optional                       :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    ptarget => this%get_entry(skey)
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key value of "//dquote(skey),                                  &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      lvalues = ptarget%sl%get_logical()
 
    else
 
      allocate(lvalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to lValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value of "//dquote(skey), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
      lvalues = false
 
    endif
 
  end subroutine get_values_as_logical_sub
 
!--------------------------------------------------------------------------------------------------
 
  !> Search through keys for a match; return logical values.
  !!
  !! THis routine allows for multiple header values to be supplied
  !! in the search for the appropriate column.
  !! @param[in]  this  Object of DICT_T class.
  !! @param[in]  slKeys String list containing one or more possible key values to
  !!                    search for.
  !! @param[out] iValues Integer vector of values associated with one of the provided keys.
 
  subroutine get_values_as_logical_given_list_of_keys_sub(this, slKeys, lValues, is_fatal)
 
    class(dict_t)                                     :: this
    type (FSTRING_LIST_T)                               :: slKeys
    logical (c_bool), allocatable, intent(out)         :: lValues(:)
    logical (c_bool), optional                         :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    integer (c_int)           :: iCount
    character (len=:), allocatable :: sText
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    icount = 0
 
    do while ( icount < slkeys%count )
 
      icount = icount + 1
 
      stext = slkeys%get( icount)
 
      ptarget => this%get_entry( stext )
 
      if ( associated( ptarget ) ) exit
 
    enddo
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key values of "//slkeys%list_all(),                             &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      lvalues = ptarget%sl%get_logical()
 
    else
 
      allocate(lvalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to lValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value(s) of: "//dquote(slkeys%list_all()), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
      lvalues = false
 
    endif
 
  end subroutine get_values_as_logical_given_list_of_keys_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_values_as_string_list_given_list_of_keys_sub(this, slKeys, slString, is_fatal )
 
    class(dict_t)                                     :: this
    type (FSTRING_LIST_T)                               :: slKeys
    type ( FSTRING_LIST_T ), intent(out)                :: slString
    logical (c_bool), optional                         :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iCount
    character (len=:), allocatable :: sText
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    icount = 0
 
    do while ( icount < slkeys%count )
 
      icount = icount + 1
 
      stext = slkeys%get( icount)
 
      ptarget => this%get_entry( stext )
 
      if ( associated( ptarget ) ) exit
 
    enddo
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key values of "//slkeys%list_all(),                             &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      slstring = ptarget%sl
 
    else
 
      call slstring%append("<NA>")
      call warn(smessage="Failed to find a dictionary entry associated with key value(s) of: "//dquote(slkeys%list_all()), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
    endif
 
  end subroutine get_values_as_string_list_given_list_of_keys_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_value_as_string_sub(this, sText, sKey, iIndex, is_fatal )
 
    class(dict_t)                                  :: this
    character(len=:), allocatable, intent(out)      :: sText
    character (len=*), intent(in), optional         :: sKey
    integer (c_int), intent(in), optional           :: iIndex
    logical (c_bool), optional                      :: is_fatal
 
    ! [ LOCALS ]
    logical (c_bool)          :: is_fatal_l
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    if ( present( skey ) )  this%current => this%get_entry(skey)
 
    if ( present( iindex ) )  this%current => this%get_entry( iindex )
 
    if ( associated( this%current ) ) then
 
      stext = this%current%sl%get( 1, this%current%sl%count )
 
    else
 
      stext= ""
 
    endif
 
  end subroutine get_value_as_string_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_values_as_string_list_sub(this, sKey, slString, is_fatal)
 
    class(dict_t)                                  :: this
    character (len=*), intent(in)                   :: sKey
    type (FSTRING_LIST_T), intent(out)               :: slString
    logical (c_bool), optional                      :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    ptarget => this%get_entry(skey)
 
    if ( present(is_fatal) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key value of "//dquote(skey),                                  &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      slstring = ptarget%sl
 
    else
 
      call slstring%append("<NA>")
      call warn(smessage="Failed to find a dictionary entry associated with key value of "//dquote(skey), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
    endif
 
 
  end subroutine get_values_as_string_list_sub
 
!--------------------------------------------------------------------------------------------------
 
  !> Search through keys for a match; return integer values.
  !!
  !! THis routine allows for multiple header values to be supplied
  !! in the search for the appropriate column.
  !! @param[in]  this  Object of DICT_T class.
  !! @param[in]  slKeys String list containing one or more possible key values to
  !!                    search for.
  !! @param[out] iValues Integer vector of values associated with one of the provided keys.
 
  subroutine get_values_as_int_given_list_of_keys_sub(this, slKeys, iValues, is_fatal)
 
    class(dict_t)                                     :: this
    type (FSTRING_LIST_T)                               :: slKeys
    integer (c_int), allocatable, intent(out)          :: iValues(:)
    logical (c_bool), optional                         :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    integer (c_int)           :: iCount
    character (len=256)            :: sText
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    icount = 0
 
    ptarget => null()
 
    do while ( icount < slkeys%count )
 
      icount = icount + 1
 
      stext = slkeys%get( icount)
 
      ptarget => this%get_entry( stext )
 
      if ( associated( ptarget ) ) exit
 
    enddo
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key values of "//slkeys%list_all(),                             &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      ivalues = ptarget%sl%get_integer()
 
    else
 
      allocate(ivalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to iValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value(s) of: "//dquote(slkeys%list_all()), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
      ivalues = itinyval
 
    endif
 
  end subroutine get_values_as_int_given_list_of_keys_sub
 
!--------------------------------------------------------------------------------------------------
 
  !> Search through keys for a match; return float values.
  !!
  !! THis routine allows for multiple header values to be supplied
  !! in the search for the appropriate column.
  !! @param[in]  this  Object of DICT_T class.
  !! @param[in]  slKeys String list containing one or more possible key values to
  !!                    search for.
  !! @param[out] fValues Float vector of values associated with one of the provided keys.
 
  subroutine get_values_as_float_given_list_of_keys_sub(this, slKeys, fValues, is_fatal)
 
    class(dict_t)                                    :: this
    type (FSTRING_LIST_T)                              :: slKeys
    real (c_float), allocatable, intent(out)          :: fValues(:)
    logical (c_bool), optional                        :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    integer (c_int)           :: iCount
    character (len=:), allocatable :: sText
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
 
    icount = 0
    ptarget => null()
 
    do while ( icount < slkeys%count )
 
      icount = icount + 1
 
      stext = slkeys%get( icount)
 
      ptarget => this%get_entry( stext )
 
      if ( associated( ptarget ) ) exit
 
    enddo
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key values of "//slkeys%list_all(),                             &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      fvalues = ptarget%sl%get_float()
 
    else
 
      allocate(fvalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to fValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value(s) of: "//dquote(slkeys%list_all()), &
        smodule=__file__, iline=__line__, iloglevel=log_debug, lecho=false)
 
 
      fvalues = ftinyval
 
    endif
 
 
  end subroutine get_values_as_float_given_list_of_keys_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine get_values_as_float_sub(this, sKey, fValues, is_fatal)
 
    class(dict_t)                                    :: this
    character (len=*), intent(in)                     :: sKey
    real (c_float), allocatable, intent(out)          :: fValues(:)
    logical (c_bool), optional                        :: is_fatal
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: pTarget
    integer (c_int)           :: iStat
    logical (c_bool)          :: is_fatal_l
    logical (c_bool)          :: empty_entries
 
    if ( present( is_fatal ) ) then
      is_fatal_l = is_fatal
    else
      is_fatal_l = false
    endif
    
    ptarget => this%get_entry(skey)
 
    if ( associated( ptarget ) ) then
 
      if ( is_fatal_l ) then
        empty_entries = ptarget%sl%empty_entries_present()
        if( empty_entries )  call warn(smessage="There are missing values associated" &
          //" with the key value of "//dquote(skey),                                  &
          iloglevel=log_all, lecho=true, lfatal=true )
      endif
 
      fvalues = ptarget%sl%get_float()
 
    else
 
      allocate(fvalues(1), stat=istat)
      call assert(istat == 0, "Failed to allocate memory to iValues array", &
        __file__, __line__)
 
      call warn(smessage="Failed to find a dictionary entry associated with key value of "//dquote(skey), &
        smodule=__file__, iline=__line__, iloglevel=log_debug , lecho=false)
 
      fvalues = ftinyval
 
    endif
 
  end subroutine get_values_as_float_sub
 
!--------------------------------------------------------------------------------------------------
 
  subroutine print_all_dictionary_entries_sub(this, iLogLevel, sDescription, lEcho )
 
    class(dict_t)                               :: this
    integer (c_int), intent(in), optional        :: iLogLevel
    character (len=*), intent(in), optional      :: sDescription
    logical (c_bool), intent(in), optional       :: lEcho
 
    ! [ LOCALS ]
    type (DICT_ENTRY_T), pointer   :: current
    character (len=512)            :: sTempBuf
    character (len=:), allocatable :: sDescription_
    integer (c_int)           :: iCount
    integer (c_int)           :: iLogLevel_l
    logical (c_bool)          :: lEcho_l
 
    if ( present( iloglevel ) ) then
      iloglevel_l = iloglevel
    else
      iloglevel_l = logs%iLogLevel
    end if
 
    if ( present( lecho ) ) then
      lecho_l = lecho
    else
      lecho_l = false
    end if
 
    if ( present( sdescription ) ) then
      sdescription_ = trim(sdescription)
    else
      sdescription_ = "dictionary data structure"
    endif
 
    current => this%first
    icount = 0
 
    call logs%write( "### Summary of all items stored in "//trim(sdescription_), &
      iloglevel=iloglevel_l, lecho=lecho_l )
 
    do while ( associated( current ) )
 
      icount = icount + 1
      stempbuf = current%key
 
      call logs%write( ascharacter(icount)//")  KEY: "//dquote(stempbuf),    &
        iloglevel=iloglevel_l, lecho=lecho_l, itab=2, ilinesbefore=1, ilinesafter=1 )
 
      select case ( iloglevel_l )
 
        case ( log_general )
 
          call current%sl%print( lu=logs%iUnitNum( log_general ) )
 
        case ( log_debug )
 
          call current%sl%print( lu=logs%iUnitNum( log_debug ) )
 
        case ( log_all )
 
          call current%sl%print( lu=logs%iUnitNum( log_general ) )
          call current%sl%print( lu=logs%iUnitNum( log_debug ) )
 
        case default
 
      end select
 
      if ( lecho_l )   call current%sl%print()
 
      current => current%next
 
    enddo
 
  end subroutine print_all_dictionary_entries_sub
 
end module dictionary