dict_zap — Removes all data from the given dictionary
inout dict dictionary ,
in destructive integer
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.
The dictionary to zap. If it is NULL then the function call has
no effect and returned value is zero.
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
The function returns the number of intems in the dictionary
before the operation.