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 and can thus be immediately reused. Thereby the object data is copied in HALCON's object database, meaning the new object contains a reference to ObjectObjectObjectObjectobjectVal, see copy_objcopy_objCopyObjCopyObjCopyObj.

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.