Docs: Dictionary vs. Event

While going through the schelp file for Dictionary in order to fix #4573, I found a lot of code examples for initializing a Dictionary like this:

d = ();

But it seems to me, that this line is actually creating an Event object instead of a Dictionary object. By creating the object like this several member functions change their behaviour, for example
.associationAt

d = Dictionary["hello" -> 5];
d.associationAt("hello");  // -> (hello -> 5)

d = ("hello": 5);
d.associationAt("hello"); // -> (nil -> nil)

So my question is: am I missing something important here or should a Dictionary really be initialized as

d = Dictionary.new;

instead of

d = ();

And if so: should the documentation be changed accordingly?

1 Like

I think you’re right. There’s some ambiguity in the documentation (and in general practice) between using “dictionary” to mean “an instance of some subclass of Dictionary” (i.e. IdentityDictionary, Environment, or Event) and using “dictionary” to mean “a concrete instance of class Dictionary.” () always returns an Event.

This is referred to in the IdentityDictionary helpfile:

Often, the subclass Event is used as an IdentityDictionary, because there is a syntactical shortcut

…and it’s sort of glossed in the Dictionary helpfile, but in a way that you’d only catch if you started reading through the method examples from the beginning, not if you came in via a search for a method name. For what it’s worth I definitely agree that Dictionary’s helpfile should use Dictionary.new throughout.

I agree with catniptwinz that the Dictionary help file should consistently use Dictionary.

Elsewhere in the documentation, we should keep the uses of IdentityDictionary and its subclasses. Dictionary is (IMO) best reserved for special cases where matching by identity won’t work and where you can afford the performance cost of matching keys by equality.

My general opinion is that the built-in help should rigorously(?) avoid syntax shortcuts, so that new users have a concrete name to look up: Event.new rather than (), or Array.fill(2, { PinkNoise.ar }) rather than { PinkNoise.ar } ! 2. But nobody actually does this when writing help.

hjh

Thanks for the clarification. I will change the code examples in the Dictionary help then, as I was anyway going to add some details to it.

1 Like

^this. shortcuts can always be included parenthetically…

1 Like