set_dict_objectT_set_dict_objectSetDictObjectSetDictObject (Operator)


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


set_dict_object(Object : : DictHandle, Key : )

Herror T_set_dict_object(const Hobject Object, const Htuple DictHandle, const Htuple Key)

void SetDictObject(const HObject& Object, const HTuple& DictHandle, const HTuple& Key)

void HDict::SetDictObject(const HObject& Object, const HTuple& Key) const

void HDict::SetDictObject(const HObject& Object, const HString& Key) const

void HDict::SetDictObject(const HObject& Object, const char* Key) const

void HDict::SetDictObject(const HObject& Object, const wchar_t* Key) const   (Windows only)

static void HOperatorSet.SetDictObject(HObject objectVal, HTuple dictHandle, HTuple key)

void HDict.SetDictObject(HObject objectVal, HTuple key)

void HDict.SetDictObject(HObject objectVal, string key)


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

This operator modifies the state of the following input parameter:

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


ObjectObjectObjectObjectobjectVal (input_object)  object(-array) objectHObjectHObjectHobject

Object to be associated with the key.

DictHandleDictHandleDictHandleDictHandledictHandle (input_control, state is modified)  dict HDict, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Dictionary handle.

Number of elements: DictHandle == 1

KeyKeyKeyKeykey (input_control)  string HTupleHTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)

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


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.

Possible Predecessors


Possible Successors




See also

create_dictcreate_dictCreateDictCreateDictCreateDict, set_dict_tupleset_dict_tupleSetDictTupleSetDictTupleSetDictTuple, get_dict_tupleget_dict_tupleGetDictTupleGetDictTupleGetDictTuple, get_dict_objectget_dict_objectGetDictObjectGetDictObjectGetDictObject, remove_dict_keyremove_dict_keyRemoveDictKeyRemoveDictKeyRemoveDictKey, get_dict_paramget_dict_paramGetDictParamGetDictParamGetDictParam