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 : )

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

void WriteDict(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)

static void HOperatorSet.WriteDict(HTuple dictHandle, HTuple fileName, HTuple genParamName, HTuple genParamValue)

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

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

def write_dict(dict_handle: HHandle, file_name: str, gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[int, float, str]]) -> None

Description

write_dictwrite_dictWriteDictWriteDictWriteDictwrite_dict writes the dictionary denoted by the DictHandleDictHandleDictHandleDictHandledictHandledict_handle to the file FileNameFileNameFileNameFileNamefileNamefile_name.

The operator supports the file formats 'hdict'"hdict""hdict""hdict""hdict""hdict" and 'json'"json""json""json""json""json" (see read_dictread_dictReadDictReadDictReadDictread_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""file_type" (see below). If neither is conclusive or set, the file is written as 'hdict'"hdict""hdict""hdict""hdict""hdict".

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

'raise_error_if_content_not_serializable'"raise_error_if_content_not_serializable""raise_error_if_content_not_serializable""raise_error_if_content_not_serializable""raise_error_if_content_not_serializable""raise_error_if_content_not_serializable":

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

'true'"true""true""true""true""true":

The default behavior, errors are raised.

'false'"false""false""false""false""false":

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

'low_level'"low_level""low_level""low_level""low_level""low_level":

The file output is the same as for 'false'"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""do_low_error" in set_systemset_systemSetSystemSetSystemSetSystemset_system.

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

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

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

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

Controls if write_dictwrite_dictWriteDictWriteDictWriteDictwrite_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 GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value must be set to 'true'"true""true""true""true""true" (default) or 'false'"false""false""false""false""false".

Execution Information

Parameters

DictHandleDictHandleDictHandleDictHandledictHandledict_handle (input_control)  dict HDict, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Dictionary handle.

Number of elements: DictHandle == 1

FileNameFileNameFileNameFileNamefileNamefile_name (input_control)  filename.write HTuplestrHTupleHtuple (string) (string) (HString) (char*)

File name.

File extension: .hdict

GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  attribute.name(-array) HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Name of the generic parameter.

Default value: []

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

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  attribute.name(-array) HTupleMaybeSequence[Union[int, float, str]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Value of the generic parameter.

Default value: []

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

Result

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

Possible Predecessors

read_dictread_dictReadDictReadDictReadDictread_dict, deserialize_handledeserialize_handleDeserializeHandleDeserializeHandleDeserializeHandledeserialize_handle, create_dictcreate_dictCreateDictCreateDictCreateDictcreate_dict

Possible Successors

read_dictread_dictReadDictReadDictReadDictread_dict, create_dictcreate_dictCreateDictCreateDictCreateDictcreate_dict

See also

read_dictread_dictReadDictReadDictReadDictread_dict, serialize_handleserialize_handleSerializeHandleSerializeHandleSerializeHandleserialize_handle, deserialize_handledeserialize_handleDeserializeHandleDeserializeHandleDeserializeHandledeserialize_handle, dict_to_jsondict_to_jsonDictToJsonDictToJsonDictToJsondict_to_json

Module

Foundation