Dictionary:
Filter:
Classes | Collections > Unordered

Dictionary : Set : Collection : Object

associative collection mapping keys to values
Subclasses: IdentityDictionary

Description

A Dictionary is an associative collection mapping keys to values. Two keys match if they are equal. (i.e. == returns true.)

The contents of a Dictionary are unordered. You must not depend on the order of items in a Dictionary. You must only rely on equality for the keys. E.g. symbols and strings can both be used as keys because the matching is done by equality (==) and not by identity (===). For identity matching, where strings can not be used as keys, see: IdentityDictionary and Event.

NOTE: Setting nil as a value erases the key from the Dictionary. This means that nil itself can't be used as a Dictionary value.

Class Methods

Dictionary.new(n: 8)

Creates a Dictionary with an initial capacity for n key value mappings.

Dictionary.newFrom(aCollection)

Creates a new Dictionary from another collection.

Arguments:

aCollection

any Object that responds to keysValuesDo (usually a List or an Array).

Discussion:

A new Dictionary can also be created from an array of Associations:

Or from a single Association like:

Inherited class methods

Instance Methods

Adding and Removing

.add(anAssociation)

Add anAssociation to the Dictionary. If the key value pair already exists in the Dictionary, the key's value will be replaced.

.put(key, value)

Associate two objects and add them to the Dictionary.

Arguments:

key

key to associate with object. This can be any objects, but is often a Symbol.

value

an object

.removeAt(key)

Remove the key and the value associated with it from the Dictionary.

.putAll( ... dictionaries)

Add all items of each argument to the dictionary.

Arguments:

... dictionaries

any Object that responds to keysValuesDo (usually a Dictionary).

.putPairs(args)

Add all items to the dictionary, using them as key and value pairwise.

Accessing

.at(key)

Access the value associated with the key.

.atFail(key, function)

Access the value associated with the key. If the key does not exist, return the result of function.

.keys(species)

Return a Set of all keys.

.values

Return a List of all values.

.atAll(keys)

From superclass: Collection

Return an Array of all values for the given keys.

.getPairs(args)

Return an Array with all keys and values pairwise.

Discussion:

Note that, unlike -asPairs, getPairs will return nil with an empty Dictionary.

.associationAt(key)

Access the Association that has the given key. Element is checked for equality (not identity).

.findKeyForValue(argValue)

Try to find a given value and return its key. Element is checked for equality (not identity).

.matchAt(key)

The dictionary's keys are used as conditions against which the arbitrary item is matched. See: matchItemReturns the associated value or nil if no key is matching the item.

NOTE: if an item matches multiple criteria, the value returned is arbitrary. This is because a dictionary is an unordered collection. It's the user's responsibility to make sure that criteria are mutually exclusive.

.trueAt(key)

Returns True if the item at the key is true, otherwise false. This method is also valid in Object.

.falseAt(key)

From superclass: Object

Returns False if the item at the key is not true, otherwise true. This method is inherited from Object.

Testing

.includes(item1)

Returns true if the specified item is stored in the Dictionary as a value. Element is checked for equality (not for identity). For identity matching see subclasses: IdentityDictionary or Event.

.includesKey(key)

Returns true if the specified item is stored in the Dictionary as a key. Element is checked for equality (not for identity). For identity matching see subclasses: IdentityDictionary or Event.

Iteration/Enumeration

Most methods for iteration work analogously to Dictionary's superclasses, see e.g. Collection.

.do(function)

.collect(function)

.reject(function)

.select(function)

.keysValuesDo(function)

Iterate over the associations, and evaluate the function for each, passing key and value as argument.

.keysValuesChange(function)

Iterate over the associations, and evaluate the function for each, passing key and value as argument. Replace the value with the return value from the function (similar to -collect, but modifies the dictionary in place).

.keysDo(function)

Iterate over the associations, and evaluate the function for each, passing key as argument.

.associationsDo(function)

Iterate over the associations, and evaluate the function for each.

.pairsDo(function)

Iterate over the associations, and evaluate the function for each, passing key and value as argument. Identical to -keysValuesDo

.invert

Return a new dictionary with all the values as keys and vice versa.

Other instance methods

.order(func)

Return an array of keys which corresponds to the order of the values of the dictionary.

.powerset

Return the set of all subsets: here an array of all sub-dictionaries.

.merge(that, func, fill: true)

Combine two dictionaries into a new one by applying a function to each value. If fill is true (default: true), values missing from one of them are kept as they are.

Arguments:

that

another dictionary.

func

a Function.

fill

a Boolean.

.blend(that, blend: 0.5, fill: true, specs)

Blend two dictionaries into a new one by interpolating each value. If fill is true (default: true), values missing from one of them are kept as they are.

Arguments:

that

another dictionary.

blend

the blend ratio as a Float between 0.0 and 1.0.

fill

a Boolean.

specs

a dictionary of Specs that are applied to each before blending.

.asSortedArray

Return the values in a sorted array of key value pairs. Sorted by key.

.asDict(mergeFunc, class)

If no arguments are passed, return itself. This is part of the Key Value Pairs interface.

Arguments:

mergeFunc

This argument is not used, but exists to make the method compatible with Collection: -asDict.

class

A dictionary class to convert to, if given (conversion is done via newFrom).

.asPairs(class)

Return the values in an array of alternating key value pairs, like [\freq, 1848, \amp, 0.2]. This is part of the Key Value Pairs interface.

Arguments:

class

The class of the collection to be returned. By default this is an Array.

Discussion:

Note that, unlike -getPairs, asPairs will return an empty Array with an empty Dictionary.

.asKeyValuePairs

See -asPairs.

.embedInStream(event)

Arguments:

event

The inval, usually in an event stream. See also Event.

If the event is not nil, yields a copy, adding all the elements of the receiver event (this leaves the receiver unchanged). If it is nil, return the receiver.

Because this pattern is mostly used in the context of events, the following code examples use the shortcut for the subclass Event instead of the Dictionary.

If a key "embedInStream" is given, use this function instead. The behaviour of the event can be configured easily this way.

The arguments event (the receiver) and inevent (the inevent) are passed to the function.

NOTE: In infinite patterns, you must call yield or embedInStream in the function, otherwise it will loop forever.

A generator for dictionaries:

Inherited instance methods

Undocumented instance methods

++(dict)

==(that)

.associationAtFail(argKey, function)

.choose

.fixCollisionsFrom(index)

.grow

.gui( ... args)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/GUI/extJITgui.sc

.hash

.isAssociationArray

.keysValuesArrayDo(argArray, function)

.mergeItem(key, val, func)

.printItemsOn(stream, itemsPerLine: 5)

.remove

.removeAtFail(key, function)

.removeFail

.scanFor(argKey)

.softPut(param, val, within: 0.025, mapped: true, lastVal, spec)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/GUI/extSoftSet.sc

.softSet(param, val, within: 0.025, mapped: true, lastVal, spec)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/GUI/extSoftSet.sc

.sortedKeysValuesDo(function, sortFunc)

.storeItemsOn(stream, itemsPerLine: 5)

.transformEvent(event)

Overview

The Difference between Dictionary, IdentityDictionary, Environment, and Event

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

Event, Environment and IdentityDictionary differ mainly insofar from Dictionary as the keys are taken to be identical (===) objects (see IdentityDictionary), instead of equal (==) objects. By consequence, the subclasses are also faster for indexing. Apart from this, the subclasses add specific functionality only.