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 |