On 8/24/10, Nicolas Cellier <nicolas.cellier.aka.nice at gmail.com> wrote:
[...snip....]

> BTW, Dictionary comment deserve a refactoring. I suggest something like
>
> A Dictionary is an unordered collection of values which are indexed by
> arbitrary keys.
> A Dictionary is thus accessed via #at: and #at:put: messages like
> SequenceableCollection, but with arbitrary keys instead of an integer
> rank.
> The keys can be any object that responds to =.
> If the key is absent, #at: raises an Error. An alternate block of code
> can be executed and its value returned in this case using
> #at:ifAbsent: (see also #at:ifAbsentPut:).
> If the key is absent, #at:put: adds a new entry to the Dictionary.
> Each key is unique: storing another value with #at:put: at an already
> used key overwrites previously associated value.
> The values are not necessarily unique, thus a Dictionary can also be
> seen as a sort of Bag with this respect.
>
> Dictionary is implemented as a HashedCollection of Association (a
> value is associated to its key).
> Being a HashedCollection enables fast random access indexed by keys.
> Consequently, keys must respond to #hash (see super).
>
> It is possible to grow or shrink a Dictionary using the messages #add:
> and #remove: with an Association parameter, however the prefered way
> to do so is using #at:put: and #removeKey:.
>
> Enumerating a Dictionary with #do: will only enumerate the values, not the
> keys.
> For enumerating keys and values, use #keysAndValuesDo:, or use
> #associationsDo: to enumerate the associations.
> #select: #reject: #collect: will operate on values while preserving
> the keys and thus answer a new Dictionary.
>
> The keys and values of a Dictionary can be extracted by sending #keys
> and #values message.
> Though the keys are theoretically a Set and values a Bag, for
> efficiency reasons, these messages will both return an Array of keys
> and an Array of values. A neat feature is that these messages are
> preserving the arbitrary storage order - in other words, (aDictionary
> values at: 3) is the value associated to key (aDictionary keys at: 3).
>
> Nicolas
>
>
 I second this comment change.

--Hannes