# setd

Definition: | setd(object key, object data, integer tid=1) putd() is a simple alias of setd() and as such behaves identically.
Description: | Add a key and data pair to a dictionary.
pwa/p2js: | Supported.
Comments: | tid can be omitted, to use the default dictionary, or the result of a previous new_dict() call. Any key can be mapped to any value, and both can be anything (integer|atom|string|[nested]sequence, including 0|NULL). It makes no difference whatsoever if you use putd() or setd(); it is simply a matter of personal preference (and in my case, forgetfulness). If the key already exists, no error occurs, and the existing previously associated data is simply overwritten. Note that it makes little sense to use reference types, such as structs, mpfr variables, or allocated memory addresses as keys: ordering would be pretty unpredictable, changing whatever they refer to would have no effect whatsoever on the behaviour of the dictionary, be that struct fields, numeric values, or memory contents, and finally should you mislay such a key there is no sensible way to recreate one, your only option would be a full traversal. Thinking in terms of an allocated memory address is the easiest way to see why: after `atom pMem = allocate(100)`, pMem might be #400860, and no amount of peek/poke on those 100 bytes would change pMem itself, whereas should you use peek(pMem) as a key, that’s different. A simple test is that if `?key` doesn’t show full and proper details, it is probably not a sensible key, though things like gdx variables are quite likely to be fine despite failing that test, that is as long as their ordering doesn’t matter, and there may well be other cases where the obstinate non-volatility of reference types as keys in dictionaries is actually an asset. Particularly in the case of a struct it would normally make much more sense to add further fields to hold additional data, rather than using a separate dictionary anyway, and much the same could be said for taking proper advantage of USER_DATA for anything xpGUI-related.
Example: |
    setd("key","data")
See Also: | getd (regarding case-insensitive keys), new_dict