Name
dict_zap — Removes all data from the given dictionary
Synopsis
dict_zap
(
|
inout dict dictionary , |
in
destructive
integer
); |
Description
The function removes all items from the given dictionary.
If the destructive
parameter is 0 or 1 then an error 22023 is signalled if the dictionary is used as a value of more than one variable.
The parameter equal to 2 forces the function to ignore the presence of multiple variables; in this case the operation may cause unexpected results in other fragments of code that share the dictionary.
In most of cases, this function is used specifically for its side effect on other variables.
With only one variable in use, one may simply set that variable to the value returned by dict_new
()
(or to NULL if the dictionary is no longer needed).
If the dictionary is no longer referenced by any variable, it is destroyed and the occupied memory is freed.
However one may wish to zap the dictionary in order to not worry about number of variables that refers to the dictionary, e.g., when dictionary is used only in some part of a long procedure.
Parameters
dict
The dictionary to zap. If it is NULL then the function call has no effect and returned value is zero.
destructive
Flag that indicates whether the dictionary can be cleaned if multiple references exist (0 and 1 = zap only if there is no other variables and signal an error otherwise, 2 = clean unconditionally).
Return Types
The function returns the number of intems in the dictionary before the operation.