Skip to content

write_dictWriteDictWriteDictwrite_dictT_write_dict🔗

Short description🔗

write_dictWriteDictWriteDictwrite_dictT_write_dict — Write a dictionary to a file.

Signature🔗

write_dict( dict DictHandle, filename.write FileName, attribute.name GenParamName, attribute.name GenParamValue )void WriteDict( const HTuple& DictHandle, const HTuple& FileName, const HTuple& GenParamName, const HTuple& GenParamValue )static void HOperatorSet.WriteDict( HTuple dictHandle, HTuple fileName, HTuple genParamName, HTuple genParamValue )def write_dict( dict_handle: HHandle, file_name: str, gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[int, float, str]] ) -> None

Herror T_write_dict( const Htuple DictHandle, const Htuple FileName, const Htuple GenParamName, const Htuple GenParamValue )

void HDict::WriteDict( const HString& FileName, const HTuple& GenParamName, const HTuple& GenParamValue ) const

void HDict::WriteDict( const HString& FileName, const HString& GenParamName, const HString& GenParamValue ) const

void HDict::WriteDict( const char* FileName, const char* GenParamName, const char* GenParamValue ) const

void HDict::WriteDict( const wchar_t* FileName, const wchar_t* GenParamName, const wchar_t* GenParamValue ) const (Windows only)

void HDict.WriteDict( string fileName, HTuple genParamName, HTuple genParamValue )

void HDict.WriteDict( string fileName, string genParamName, string genParamValue )

Description🔗

write_dictWriteDict writes the dictionary denoted by the DictHandledictHandledict_handle to the file FileNamefileNamefile_name.

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

Note that due to restrictions of the '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_dictWriteDict 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'"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 GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value, respectively. Some of the optional parameters can only be set for a certain file type. The following values for GenParamNamegenParamNamegen_param_name are possible:

  • 'raise_error_if_content_not_serializable'"raise_error_if_content_not_serializable": If DictHandledictHandledict_handle contains an item that can not be serialized, an exception is raised per default. This behavior is controlled by this parameter, for which GenParamValuegenParamValuegen_param_value can take the following values:

    • 'true'"true": The default behavior, errors are raised.

    • 'false'"false": The errors are suppressed. Depending on the file type an empty handle ('hdict'"hdict") or no entry at all ('json'"json") are written in place of the non serializable item.

    • 'low_level'"low_level": The file output is the same as for '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" in set_systemSetSystem.

  • 'file_type'"file_type": Sets the file type to be used. The corresponding entry in GenParamValuegenParamValuegen_param_value must be set to 'hdict'"hdict" (default) or '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" is used.

  • '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 GenParamValuegenParamValuegen_param_value must be set to 'true'"true" (default) or 'false'"false".

  • 'use_json_arrays'"use_json_arrays": Controls if write_dictWriteDict 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 GenParamValuegenParamValuegen_param_value must be set to 'true'"true" (default) or 'false'"false".

Execution information🔗

Execution information

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Processed without parallelization.

Parameters🔗

DictHandledictHandledict_handle (input_control) dict → (handle)HTuple (HHandle)HDict, HTuple (IntPtr)HHandleHtuple (handle)

Dictionary handle.

Number of elements: DictHandle == 1

FileNamefileNamefile_name (input_control) filename.write → (string)HTuple (HString)HTuple (string)strHtuple (char*)

File name.

File extension: .hdict

GenParamNamegenParamNamegen_param_name (input_control) attribute.name(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Name of the generic parameter.

Default: [][]
List of values: 'compact_json', 'file_type', 'raise_error_if_content_not_serializable', 'use_json_arrays'"compact_json", "file_type", "raise_error_if_content_not_serializable", "use_json_arrays"

GenParamValuegenParamValuegen_param_value (input_control) attribute.name(-array) → (string / integer / real)HTuple (HString / Hlong / double)HTuple (string / int / long / double)MaybeSequence[Union[int, float, str]]Htuple (char* / Hlong / double)

Value of the generic parameter.

Default: [][]
Suggested values: 'hdict', 'json', 'true', 'false', 'low_level'"hdict", "json", "true", "false", "low_level"

Result🔗

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

Combinations with other operators🔗

Combinations

Possible predecessors

read_dictReadDict, deserialize_handleDeserializeHandle, create_dictCreateDict

Possible successors

read_dictReadDict, create_dictCreateDict

See also

read_dictReadDict, serialize_handleSerializeHandle, deserialize_handleDeserializeHandle, dict_to_jsonDictToJson

Module🔗

Foundation