Mapping and Lists: the dictionaries module

type dictionary

Opaque type of the dictionaries module, that is used to serialize and store data information. When using it as a entity in a given scoping unit, it has to be declared with the pointer attribute, as it refers to internal storage data, not directly accessible. For this reason its status is undefined after declaration. Each dictionary has to be therefore iniitalized via calls to dict_init() function, of by association to the dict_new() function.

Public procedures
Constructors/Destructors: Accessors:
dict_init() dict_len()
dict_new() dict_size()
dict_free() dict_key()
list_new() dict_item()
function dict_free(dict[, dictA, dictB, ...])

Free and nullify the dictionary. Optionally accepts up to ten different dictionaries as arguments.

Parameters:

dict [dictionary,inout,pointer] :: The dictionary to be freed. Nullified on output. The same applied to the optional arguments dict1, dict2, etc.
Example :
program freedict
  use dictionaries
  implicit none
  type(dictionary), pointer :: dict1, dict2
  [...]
  call dict_free(dict1)
  call dict_free(dict2)
  !or instead
  !call dict_free(dict1,dict2)
end program freedict
subroutine dict_init(dict)

Initialize a dictionary, ready for usage. The dictionary may be undefined on input, thus care must be taken in freeing previously initialized instances before calling dict_init() again. :Example:

program dictinit
  use dictionaries
  implicit none
  type(dictionary), pointer :: dict
  call dict_init(dict)
  ![...] perform actions with the dict
  call dict_free(dict)
  !and then dict (which is now nullified) might be reinitialized again
end program dictinit
Parameters:dict [dictionary,pointer] :: the dictionary to be iniitalized
Called from:f_err_initialize(), get_list_ptr(), bind_dict_pop(), dict_new(), bind_dict_init(), yaml_load(), list_new(), get_child_ptr(), dict_new_elems(), init_next(), dict_copy(), yaml_cl_parse_option(), yaml_parse_(), input_file_minimal(), yaml_cl_parse_init(), get_dict_from_key(), list_new_elems(), input_keys_control()
Call to:dictionary_nullify(), allocate_file()
function list_new([[entity-list] [entity, [,entity] ...]])

Prepare storage data in the dictionries database ans provides a pointer to it. The function f:func:list_new conceives the database as a list. Optionally a comma-separated list of entities can be provided, or, alternatively an array of them. If more thant one argument is present, or if an array is provided as a single argument, the stored dictionary should be interpreted as a list, in arguments or array element order, respectively.

Each entity is described as a

.item. value

The variable value may be any scalar object of intrinsic type, or a dictionary pointer variable. The variable might also be a fortran array of intrinsic type and rank one, in which case list_new() returns a pointer to a list whose items correspond to value elements in array element order.

Return:

list_new [dictionary,inout,pointer] :: reference to the stored data
Example :
  dict_tmp => list_new([.item. 'one',.item. '4',.item. '1.1'])

use dictionaries
real(f_double) :: var
real(f_double), dimension(3) :: arr
type(dictionary), pointer :: list
![...]
list => list_new(.item. arr)
!retrieval
val = list // 0 !this corresponds to val=arr(1)
val = list // 1 !this corresponds to val=arr(2)
val = list // 2 !this corresponds to val=arr(3)
call dict_free(list)
function dict_new([[entity-list] [entity, [,entity] ...]])

Prepare storage data in the dictionries database ans provides a pointer to it. When called without arguments the association to the dict_new() function is identical to a dict_init() routine. Optionally a comma-separated list of entities can be provided, or, alternatively an array of them. If more thant one argument is present, or if an array is provided as a single argument, the stored dictionary should be interpreted as a ordered mapping, in arguments or array element order, respectively.

Each entity is described as a

key .is. value

where key is a string. The variable value may be any scalar object of intrinsic type, or a dictionary pointer variable.

Return:

dict_new [dictionary,inout,pointer] :: reference to the stored data
Example :
  dict1=>dict_new()

  dictA=>dict_new('Key' .is. 'Scalar')

  dict1=>dict_new(['Key1' .is. 'One',&
       'Key2' .is. 'Two','Key3' .is. 'Three'])

   subd => dict_new(  &
         & "__exclusive__" .is. dict_new( "123" .is. "operation 123", &
         &                                  "456" .is. "operation 456" ), &
         & "__default__"   .is. list_new(.item."1.", .item."2.", .item."3." ) )
function dict_len(dict)

Provides the length of the dictionary in the case it is used as a list of objects. Returns 0 if the dictionary is a mapping or a scalar. The return value is -1 is the dictionary is nullified. For mapping the dict_size() function will have to be used.

Attributes :

pure
Example :
program dictlen
  use dictionaries
  implicit none
  integer :: ilen
  type(dictionary), pointer :: dict
  call dict_init(dict)
  call dict_add(dict,'item1')
  call dict_add(dict,'item2')
  call dict_add(dict,'item3')
  ilen = dict_len(dict) !ilen has value 3
  call dict_free(dict)
  ilen = dict_len(dict) !ilen has value -1
end program dictlen
Parameters:

dict [dictionary,in,pointer]
Return:

dict_len [integer] :: Length of the dict as list container
Called from:

pop_item(), bind_dict_len(), bind_dict_append(), list_scalar(), bind_dict_move_to_item(), dict_remove_last(), key_in_dictionary(), input_keys_set(), dict_copy(), input_file_complete(), pop_key(), dict_next_build_list(), dicts_are_equal(), dict_update(), f_err_check()
function dict_size(dict)

Provides the length of the dictionary in the case it is used as a mapping of objects. Returns 0 if the dictionary is a list or a scalar. The return value is -1 is the dictionary is nullified. For lists the dict_len() function will have to be used.

Attributes :

pure
Example :
program dictlen
  use dictionaries
  implicit none
  integer :: isize
  type(dictionary), pointer :: dict
  call dict_init(dict)
  call dict_set(dict//'key1','value1')
  call dict_set(dict//'key2','value2')
  call dict_set(dict//'key3','value3')
  isize = dict_size(dict) !ilen has value 3
  call dict_free(dict)
  isize = dict_size(dict) !ilen has value -1
end program dictlen
Parameters:

dict [dictionary,in,pointer]
Return:

dict_size [integer] :: Length of the dict as mapping container
Called from:

pop_item(), list_scalar(), input_keys_set(), dict_copy(), input_file_complete(), pop_key(), dicts_are_equal(), dict_update(), bind_dict_size()
function dict_key(dict)

Returns the value of the key of the dictionary. Useful especially when using the dictionary as an iterator among a mapping

Attributes :

pure
Example :
   dict_tmp=>dict_iter(dictA)
   do while(associated(dict_tmp))
      call yaml_map('Iterating in dictA',.true.)
      call yaml_map('Key of dictA',dict_key(dict_tmp))
      call yaml_map('Value of dictA',dict_value(dict_tmp))
      dict_tmp=>dict_next(dict_tmp)
   end do
Parameters:

dict [dictionary,in,pointer]
Return:

dict_key [character] :: key of dict, empty string if nullified
Called from:

input_keys_fill(), input_file_dump(), input_keys_set(), input_file_complete(), yaml_cl_parse_option(), yaml_parse_error_throw(), dict_keys(), input_file_minimal(), bind_dict_key(), yaml_cl_parse_init(), yaml_cl_parse_cmd_line(), parser_help(), input_keys_control()
function dict_item(dict)

Returns the value of the item of the dictionary. Useful especially when using the dictionary as an iterator among a mapping

Attributes :

pure
Example :
   dict_tmp=>dict_next(dictA)
   do while(associated(dict_tmp))
      call yaml_map('Item of dictA',dict_item(dict_tmp))
      call yaml_map('Key of dictA',dict_key(dict_tmp))
      call yaml_map('Value of dictA',dict_value(dict_tmp))
      dict_tmp=>dict_next(dict_tmp)
   end do
   call dict_free(dictA)
Parameters:

dict [dictionary,in,pointer]
Return:

dict_item [integer] :: item of dict, -1 if nullified
function dict_value(dict)

Returns the value dictionary. Useful especially when using the dictionary as an iterator among a mapping. Useful for scalar values. If the value is not a scalar, it returns either :f:var`TYPE_DICT` or TYPE_LIST.

Attributes :

pure
Example :
   dict_tmp=>dict_next(dictA)
   do while(associated(dict_tmp))
      call yaml_map('Item of dictA',dict_item(dict_tmp))
      call yaml_map('Key of dictA',dict_key(dict_tmp))
      call yaml_map('Value of dictA',dict_value(dict_tmp))
      dict_tmp=>dict_next(dict_tmp)
   end do
   call dict_free(dictA)
Parameters:

dict [dictionary,in,pointer]
Return:

dict_value [character] :: value of the dictionary, meaningful if scalar.
Called from:

yaml_load(), input_keys_set(), input_file_complete(), yaml_parse_error_throw(), dict_islist(), input_file_minimal(), bind_dict_value(), dicts_are_equal(), dict_isdict(), dict_isscalar(), yaml_cl_parse_cmd_line()

and again

and yet again

function f_err_check([err_id[, err_name]])

Returns .true. is the error identified by the input arguments is present, .false. otherwse. If the arguments are absent returns .true. if any arror has been produced

Options:
  • err_id [integer,in,optional] :: The code of the error to be checked for
  • err_name [character,in,optional] :: Name of the error to search
Return:

f_err_check [logical]
Called from:

bind_err_check_by_name(), bind_err_check_by_id(), yaml_parse_(), bind_err_check(), yaml_cl_parse_cmd_line()
Call to:

dict_len()