new_dict

Definition: integer tid = new_dict(sequence kd_pairs={}, integer pool_only=0)
-- or --
integer tid = new_dict(string dictname="")
Description: Creates a new dictionary, so that clashes with other uses of {key,data} pairings can be avoided, and optionally initialises it with a set of {key,data} pairs, or a diagnostic name.
Comments: If kd_pairs is a string then it is treated as a name for the dictionary, which may be useful for diagnostic purposes, and can be retrieved using dict_name(). Otherwise every element of kd_pairs, if present, should be a sequence of length 2, and said {key,data} gets passed to setd(), along with the id of the newly created dictionary.

The returned tid is intended to be passed as the last parameter to setd(), getd(), deld(), destroy_dict(), traverse_dict(), and similar, taking care not to miss any.

For smaller applicatons, there is a default dictionary, 1, that can be used without ever calling new_dict(), however larger applications and in particular third party components will obviously benefit from keeping their data private (by the simple act of not sharing their tid1).

When you have no further use for it, an entire dictionary can be removed by invoking destroy_dict(tid), except for the default dictionary, 1, as mentioned above, which is special and is the only dictionary that cannot be deleted - attempts to do so merely empty it and leave it still available for use.

Dictionaries are not thread-safe, for details of that, or if you are curious about the mysterious pool_only parameter, see the Technicalia drop-down.
Disclaimer: 1Rogue code that wantonly writes garbage to a tid of, say, 5, when it did not obtain that 5 from new_dict(), can obviously wreak havoc. Should it ever prove necessary it would probably be fairly easy to change integer tid to {integer tid, string passkey} just to make it far harder to accidentally replicate a tid.
Example 1:
integer tid = new_dict({{1,"one"},{2,"two"}})
Example 2:
-- multithreaded applications need to use locking (see Technicalia)
integer dictcs = init_cs(), tid
    enter_cs(dictcs)
    tid = new_dict("thread data")
    leave_cs(dictcs)
See Also: enter_cs, destroy_dict