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 (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

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