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.