write_dictT_write_dictWriteDictWriteDictwrite_dict (Operator)

Name

write_dictT_write_dictWriteDictWriteDictwrite_dict — Write a dictionary to a file.

Signature

write_dict( : : DictHandle, FileName, GenParamName, GenParamValue : )

Description

write_dictwrite_dictWriteDictWriteDictwrite_dict writes the dictionary denoted by the DictHandleDictHandleDictHandledictHandledict_handle to the file FileNameFileNameFileNamefileNamefile_name.

The operator supports the file formats 'hdict'"hdict""hdict""hdict""hdict" and 'json'"json""json""json""json" (see read_dictread_dictReadDictReadDictread_dict). The format is selected based on the filename ending or by using the generic parameter 'file_type'"file_type""file_type""file_type""file_type" (see below). If neither is conclusive or set, the file is written as 'hdict'"hdict""hdict""hdict""hdict".

Note that due to restrictions of the 'json'"json""json""json""json"-format, some information contained in dictionaries can not be stored in that file format. This includes iconic objects and handles that are not dictionaries. By default, write_dictwrite_dictWriteDictWriteDictwrite_dict will return an error if the dictionary contains such an item. This behavior can be changed using the generic parameter 'raise_error_if_content_not_serializable' (see below).

A set of additional optional parameters can be set. The names and values of the parameters are passed in GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value, respectively. Some of the optional parameters can only be set for a certain file type. The following values for GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name are possible:

'raise_error_if_content_not_serializable':

If DictHandleDictHandleDictHandledictHandledict_handle contains an item that can not be serialized, an exception is raised per default. This behavior is controlled by this parameter, for which GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value can take the following values:

'true'"true""true""true""true":: The default behavior, errors are raised.
'false'"false""false""false""false":: The errors are suppressed. Depending on the file type an empty handle ('hdict'"hdict""hdict""hdict""hdict") or no entry at all ('json'"json""json""json""json") are written in place of the non serializable item.
'low_level'"low_level""low_level""low_level""low_level":: The file output is the same as for 'false'"false""false""false""false". Additionally, low level errors are raised if non-serializable items are encountered. The behavior regarding HALCON low level errors is determined by 'do_low_error'"do_low_error""do_low_error""do_low_error""do_low_error" in set_systemset_systemSetSystemSetSystemset_system.

'file_type'"file_type""file_type""file_type""file_type":

Sets the file type to be used. The corresponding entry in GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value must be set to 'hdict'"hdict""hdict""hdict""hdict" (default) or 'json'"json""json""json""json". If this parameter is not set, the file type is determined based on the ending of the file name. If that ending is not conclusive, the default 'hdict'"hdict""hdict""hdict""hdict" is used.

'compact_json'"compact_json""compact_json""compact_json""compact_json":

Controls if JSON files are written in a compact format without additional whitespace, or human-readable with newlines and indentation. In both cases the file will contain the same information. The corresponding entry in GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value must be set to 'true'"true""true""true""true" (default) or 'false'"false""false""false""false".

'use_json_arrays'"use_json_arrays""use_json_arrays""use_json_arrays""use_json_arrays":

Controls if write_dictwrite_dictWriteDictWriteDictwrite_dict should convert dictionaries into native JSON arrays where possible. For this, the dictionaries must only contain ascending integer keys starting at zero. The corresponding entry in GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value must be set to 'true'"true""true""true""true" (default) or 'false'"false""false""false""false".

Execution Information

Multithreading type: independent (runs in parallel even with exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters

DictHandleDictHandleDictHandledictHandledict_handle (input_control) dict → (handle)

Dictionary handle.

Number of elements: DictHandle == 1

FileNameFileNameFileNamefileNamefile_name (input_control) filename.write → (string)

File name.

File extension: .hdict

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control) attribute.name(-array) → (string)

Name of the generic parameter.

Default: []

List of values: 'compact_json'"compact_json""compact_json""compact_json""compact_json", 'file_type'"file_type""file_type""file_type""file_type", 'raise_error_if_content_not_serializable', 'use_json_arrays'"use_json_arrays""use_json_arrays""use_json_arrays""use_json_arrays"

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control) attribute.name(-array) → (string / integer / real)

Value of the generic parameter.

Default: []

Suggested values: 'hdict'"hdict""hdict""hdict""hdict", 'json'"json""json""json""json", 'true'"true""true""true""true", 'false'"false""false""false""false", 'low_level'"low_level""low_level""low_level""low_level"

Result

If the parameters are valid, the operator write_dictwrite_dictWriteDictWriteDictwrite_dict returns the value 2 ( H_MSG_TRUE) . If necessary an exception is raised.