create_dictCreateDictCreateDictcreate_dictT_create_dict🔗

Short description🔗

create_dictCreateDictCreateDictcreate_dictT_create_dict — Create a new empty dictionary.

Signature🔗

create_dict( out dict DictHandle )void CreateDict( HTuple* DictHandle )def create_dict( ) -> HHandle

void HDict::HDict( )

public HDict( )

void HDict::CreateDict( )

void HDict.CreateDict( )

Description🔗

create_dictCreateDict creates a new empty dictionary and returns it in DictHandledictHandledict_handle.

The dictionary serves as an associative array-like container allowing to store an arbitrary number of values associated with unique keys (integers or strings). Each key can refer either to a tuple or to an iconic object. These are stored in the dictionary using set_dict_tupleSetDictTuple or set_dict_objectSetDictObject, respectively, from where they can be retrieved again using get_dict_tupleGetDictTuple or get_dict_objectGetDictObject.

The data stored in the dictionary is always a copy of the original data, being it control parameters or objects. The original data can thus be reused immediately after the set_dict_tupleSetDictTuple or set_dict_objectSetDictObject calls. The following particularities apply:

Objects: The copy is a reference, as in copy_objCopyObj. In particular, changes made using the operators set_grayvalSetGrayval or overpaint_regionOverpaintRegion affect the object stored in the dictionary as well.
Handles: Storing any handle in the dictionary will copy the handle value, but not the resource behind the handle.

Multiple threads can add, retrieve and remove keys concurrently as long as every thread accesses a different key. As an exception to this rule, multiple threads can retrieve the same key from a dictionary simultaneously.

HDevelop In-line Operation🔗

HDevelop provides an in-line operation for create_dictCreateDict, which can be used in an expression in the following syntax:

texttt{DictHandle := dict{}texttt{}}

Execution information🔗

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 returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters🔗

DictHandledictHandledict_handle (output_control) dict → (handle)HTuple (HHandle)HDict, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the newly created dictionary.

Number of elements: DictHandle == 1

Example🔗

(HDevelop)

Dicts := []
for idx := 0 to 4 by 1
  create_dict (DictHandle)
  Dicts[idx] := DictHandle
endfor
* ...

Result🔗

Returns 2 (H_MSG_TRUE) unless a resource allocation error occurs.

Combinations with other operators🔗

Combinations

Possible successors

set_dict_tupleSetDictTuple, set_dict_objectSetDictObject

Module🔗

Foundation