set_dict_objectT_set_dict_objectSetDictObjectSetDictObject (Operator)

Name

set_dict_objectT_set_dict_objectSetDictObjectSetDictObject — Add a key/object pair to the dictionary.

Signature

set_dict_object(Object : : DictHandle, Key : )

Description

set_dict_objectset_dict_objectSetDictObjectSetDictObjectSetDictObject stores an object associated with a key in the dictionary. The dictionary is denoted by the DictHandleDictHandleDictHandleDictHandledictHandle parameter.

ObjectObjectObjectObjectobjectVal is copied by the operation (copying the object data in HALCON's object database, see copy_objcopy_objCopyObjCopyObjCopyObj), and can thus be immediately reused. Both an empty object or an object tuple are considered as a valid value that can be associated with the key. If any data (tuple or object) was already associated with given key (KeyKeyKeyKeykey), the old data is destroyed by set_dict_objectset_dict_objectSetDictObjectSetDictObjectSetDictObject and replaced by ObjectObjectObjectObjectobjectVal.

The KeyKeyKeyKeykey has to be a string or an integer. Strings are treated case sensitive.

The object data for the given key can be retrieved again from the dictionary using get_dict_objectget_dict_objectGetDictObjectGetDictObjectGetDictObject.

Execution Information

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

This operator modifies the state of the following input parameter:

DictHandleDictHandleDictHandleDictHandledictHandle

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

ObjectObjectObjectObjectobjectVal (input_object) object(-array) → object

Object to be associated with the key.

DictHandleDictHandleDictHandleDictHandledictHandle (input_control, state is modified) dict → (handle)

Dictionary handle.

Number of elements: DictHandle == 1

KeyKeyKeyKeykey (input_control) string → (string / integer)

Key string.

Number of elements: Key == 1

Restriction: length(Key) > 0

Example (HDevelop)

create_dict (Dict)
read_image (Image, 'filename')
set_dict_object (Image, Dict, 'my_image')

Result

If the operation succeeds, set_dict_tupleset_dict_tupleSetDictTupleSetDictTupleSetDictTuple returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters (handle or key) or resource allocation error.