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: bind_dict_pop(), bind_dict_init(), list_new(), dict_new(), dict_copy(), f_err_initialize(), f_err_clean(), f_err_pop(), f_err_open_try(), get_child_ptr(), get_dict_from_key(), init_next(), get_list_ptr(), f_update_database(), f_malloc_dump_status(), f_bib_initialize(), input_file_minimal(), f_object_signal_connect(), f_ref_new(), f_timing_category(), f_timing_initialize(), yaml_output_errors(), yaml_close_stream(), yaml_cite(), yaml_cl_parse_option(), yaml_load()
Call to: dictionary_nullify()

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

bind_dict_move_to_item(), bind_dict_append(), bind_dict_len(), dict_remove_last(), dict_update(), dict_copy(), f_err_check(), f_get_error_dict(), f_get_no_of_errors(), f_get_last_error(), f_err_pop(), f_purge_database(), input_file_complete(), f_iostream_from_lstring(), f_iostream_get_line(), f_object_signal_prepare(), f_object_signal_emit(), f_object_signal_connect(), f_timing_category(), get_category_name(), yaml_dict_dump(), yaml_dict_dump_all()

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

bind_dict_size(), dict_update(), dict_copy(), f_malloc_finalize(), f_malloc_dump_status(), input_file_complete(), yaml_close_stream(), yaml_dict_dump()

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(len=max_field_length)] :: key of dict, empty string if nullified

Called from

bind_dict_key(), dict_keys(), f_release_routine(), input_file_complete(), input_file_minimal(), input_file_dump(), yaml_close_stream(), yaml_bib_dump(), yaml_dict_dump(), yaml_cl_parse_option(), yaml_cl_parse_cmd_line()

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

Called from

yaml_dict_dump()

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(len=max_field_length)] :: value of the dictionary, meaningful if scalar.

Called from

bind_dict_value(), dict_islist(), dict_isdict(), dict_isscalar(), input_file_complete(), input_file_minimal(), f_iostream_get_line(), yaml_cite(), yaml_bib_dump(), yaml_dict_dump(), yaml_cl_parse_cmd_line(), yaml_load()

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,] :: The code of the error to be checked for
err_name [character(len=*), in,] :: Name of the error to search

Return

f_err_check [logical]

Called from

f_err_close_try(), bind_err_check(), bind_err_check_by_id(), bind_err_check_by_name(), yaml_cl_parse_cmd_line()

Call to

dict_len()

Mapping and Lists: the dictionaries module¶

Mapping and Lists: the `dictionaries` module¶