destroy_dict

Definition: destroy_dict(integer tid, bool justclear=false)
Description: Completely remove a dictionary, including any {key,data} pairings it contains.
Comments: Invoke destroy_dict(tid) when you have no further use for the specified dictionary. Destruction is near-instantaneous, and obviously that is significantly faster than deleting all the keys individually.

Note that destroy_dict(1) simply empties the default dictionary completely, but leaves it available for future use.
A similar thing happens on other dictionaries if the justclear parameter is non-zero.

Attempts to use a dictionary (other than 1/the default) after destroy_dict (with justclear=0) has been called, but before that slot has been resurrected via a subsequent call to new_dict(), or of course other values not originating from a call to new_dict(), are expected to fail with "invalid dictionary id".

It is (and should be) perfectly legal to destroy_dict(1) at the very start.
In contrast, destroy_dict(5) is fatal when 5 is not valid (including shortly after destroy_dict(5), as above).
Example:
destroy_dict(tid)
See Also: new_dict