write_dictT_write_dictWriteDictWriteDictwrite_dict (Operator)
Name
write_dictT_write_dictWriteDictWriteDictwrite_dict — Write a dictionary to a file.
Signature
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)
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
- Multithreading type: independent (runs in parallel even with exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
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
See also
read_dictread_dictReadDictReadDictReadDictread_dict,
serialize_handleserialize_handleSerializeHandleSerializeHandleSerializeHandleserialize_handle,
deserialize_handledeserialize_handleDeserializeHandleDeserializeHandleDeserializeHandledeserialize_handle
Module
Foundation