Collection | SuperCollider 3.12.2 Help

Subclasses: Array2D, Bag, Interval, MultiLevelIdentityDictionary, … see all

Description

Collection is an abstract class. You do not create direct instances of Collection. There are many types of Collections including List, Array, Dictionary, Bag, Set, SortedList, etc. See Collections for a complete class tree.

Class Methods

Collection.newFrom(aCollection)

Creates a new Collection from another collection. This supports the interface for the method "as".Array.newFrom(Set[4, 2, 1]); Set.newFrom(Array[4, 2, 1]); [1, 2, 3, 4, 3, 2].as(Set); // as(someClass) calls someClass.newFrom(this)

Collection.with( ... args)

Creates a new Collection from the args.Array.with(4, 2, 1);

Collection.fill(size, function)

Creates a Collection of the given size, the elements of which are determined by evaluation the given function. The function is passed the index as an argument.Array.fill(4, { arg i; i * 2 }); Bag.fill(14, { arg i; i.rand });

Arguments:

size	The size of the collection which is returned. If nil, it returns an empty collection. If an array of sizes is given, the resulting collection has the appropriate dimensions (see: fillND).Array.fill([2, 2, 3], { arg i, j, k; i 100 + (j * 10) + k });
function	The function which is called for each new element - the index is passed in as a first argument. The function be anything that responds to the message "value".Array.fill(10, { arg i; 2 ** i }); Array.fill(10, Pxrand([0, 1, 2], inf).iter); Array.fill(10, 7); // an object that doesn't respond with a new value is just repeatedly added.

Collection.fill2D(rows, cols, function)

Creates a 2 dimensional Collection of the given sizes. The items are determined by evaluation of the supplied function. The function is passed row and column indexes as arguments. See J concepts in SCArray.fill2D(2, 4, 0); Array.fill2D(3, 4, { arg r, c; r*c+c; });

Collection.fill3D(planes, rows, cols, function)

Creates a 3 dimensional Collection of the given sizes. The items are determined by evaluation of the supplied function. The function is passed plane, row and column indexes as arguments. See J concepts in SCArray.fill3D(2, 3, 4, { arg p, r, c; p; });

Collection.fillND(dimensions, function, args: [ ])

Creates a N dimensional Collection where N is the size of the array dimensions. The items are determined by evaluation of the supplied function. The function is passed N number of indexes as arguments. See J concepts in SCArray.fillND([4, 4], { arg a, b; a+b; }); // 2D Array.fillND([4, 4, 4], { arg a, b, c; a+b*c; }); // 3D Array.fillND([1, 2, 3, 4], { arg a, b, c, d; b+d; }); // 4D

Inherited class methods

Instance Methods

Accessing

.size

Answers the number of objects contained in the Collection.List[1, 2, 3, 4].size;

.isEmpty

Answer whether the receiver contains no objects.List[].isEmpty;

Adding and Removing

.add

Add anObject to the receiver.List[1, 2].add(3);

.addAll(aCollection)

Add all items in aCollection to the receiver.List[1, 2].addAll(List[3, 4]);

.remove

Remove anObject from the receiver. Answers the removed object.( var a; a = List[1, 2, 3, 4]; a.remove(3); a; )

.removeAll(list)

Remove all items in aCollection from the receiver.List[1, 2, 3, 4].removeAll(List[2, 3]);

NOTE: that multiple items in the receiver will not necessarily be removed

See -removeEvery for a related method that removes all occurrences.

.removeEvery(list)

Remove all occurrences of the items in aCollection from the receiver.List[1, 2, 3, 2, 3, 2, 3, 4].removeEvery(List[2, 3]);

.removeAllSuchThat(function)

Remove all items in the receiver for which function answers True. The function is passed two arguments, the item and an integer index. Answers the objects which have been removed.( var a; a = List[1, 2, 3, 4]; a.removeAllSuchThat({ arg item, i; item < 3 }); a; )

.putEach(keys, values)

Put the values in the corresponding indices given by keys. If one of the two argument arrays is longer then it will wrap.y = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; y.putEach([4, 7], [\smelly, \head]); y.putEach([2, 3, 5, 6], \wotsits);

.atAll(keys)

Return a collection of all the items for the keys.y = [\a, \b, \c]; y.atAll([0, 2]);

Testing

.includes(item1)

Answer whether anObject is contained in the receiver.List[1, 2, 3, 4].includes(3);

.includesEqual(item1)

Answer whether anObject is contained in the receiver. In contrast to -includes this tests for equality - not identity.List["a", "b", "c"].includesEqual("c"); //true List["a", "b", "c"].includes("c"); //false List[ List[1, 2], List[3, 4] ].includesEqual(List[3, 4]); //true List[ List[1, 2], List[3, 4] ].includes(List[3, 4]); //false

.includesAny(aCollection)

Answer whether any item in aCollection is contained in the receiver.List[1, 2, 3, 4].includesAny(List[4, 5]);

.includesAll(aCollection)

Answer whether all items in aCollection are contained in the receiver.List[1, 2, 3, 4].includesAll(List[4, 5]);

.matchItem(item)

Returns True if this includes the item.

Iteration

.do

Evaluates function for each item in the collection. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].do({ arg item, i; item.postln });

.collect(function)

Answer a new collection which consists of the results of function evaluated for each item in the collection. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].collect({ arg item, i; item + 10 });

If you want to control what type of collection is returned, use -collectAs(function, class).

.select(function)

Answer a new collection which consists of all items in the receiver for which function answers True. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].select({ arg item, i; item.even });

If you want to control what type of collection is returned, use -selectAs(function, class).

.reject(function)

Answer a new collection which consists of all items in the receiver for which function answers False. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].reject({ arg item, i; item.even });

If you want to control what type of collection is returned, use -rejectAs(function, class).

.detect(function)

Answer the first item in the receiver for which function answers True. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].detect({ arg item, i; item.even });

.detectIndex(function)

Similar to -detect but returns the index instead of the item itself.List[1, 2, 3, 4].detectIndex({ arg item, i; item.even });

.inject(thisValue, function)

In functional programming, the operation known as a left fold. inject takes an initial value and a function and combines the elements of the collection by applying the function to the accumulated value and an element from the collection starting from the first element in the collection. The function takes two arguments and returns the new value. The accumulated value is initialized to initialValue.[1,2,3,4,5].inject(0, _+_); // 15 [1,2,3,4,5].inject(1, _*_); // 120 // same as .collect(_.squared) [1,2,3,4,5].inject([], {|a,b| a ++ b.squared }); // [ 1, 4, 9, 16, 25 ] [1,2,3,4,5].inject([], {|a,b| [b] ++ a ++ [b]}); // [ 5, 4, 3, 2, 1, 1, 2, 3, 4, 5 ] [1,2,3,4,5].inject([], {|a,b| a ++ b ++ a}); [1,2,3,4,5].inject([], {|a,b| a ++ a ++ b});

.injectr(thisValue, function)

In functional programming, the operation known as a right fold. inject takes an initial value and a function and combines the elements of the collection by applying the function to the accumulated value and an element from the collection starting from the last element in the collection. The function takes two arguments and returns the new value. The accumulated value is initialized to initialValue.[1,2,3,4,5].injectr([], _++_); // [ 5, 4, 3, 2, 1 ] [1,2,3,4,5].inject([], _++_); // [ 1, 2, 3, 4, 5 ]

.collectInPlace(function)

Iterate over the collection and replace each item with a new one, returned by the function. This can be useful when one wants to aviod creating a new array in memory. In most cases, it is better to use -collect.a = [1, 5, 3, 4]; a.collectInPlace { |x| 2 ** x }; a; // changed // compare: a = [1, 5, 3, 4]; a.collect { |x| 2 ** x }; a; // remains unchanged

.collectCopy(func)

Like -collect, but the collection is copied before iteration. This is recommended wherever the function may change the collection itself.a = [1, 5, 2, 3, 4]; b = a.collectCopy { |x| if(x.even) { a.remove(x); "removed" } { x } }; a; b;

.any(function)

Answer whether function answers True for any item in the receiver. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].any({ arg item, i; item.even });

.every(function)

Answer whether function answers True for every item in the receiver. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].every({ arg item, i; item.even });

.count(function)

Answer the number of items for which function answers True. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].count({ arg item, i; item.even });

.occurrencesOf(obj)

Answer the number of items in the receiver which are equal to anObject.List[1, 2, 3, 3, 4, 3, 4, 3].occurrencesOf(3);

.sum(function)

Answer the sum of the results of function evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.List[1, 2, 3, 4].sum; (0..8).sum { |i| 1 / (2 ** i) };

.maxItem(function)

Answer the maximum of the results of function evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index. If function is nil, then answer the maximum of all items in the receiver.List[1, 2, 3, 4].maxItem({ arg item, i; item + 10 });

.minItem(function)

Answer the minimum of the results of function evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index. If function is nil, then answer the minimum of all items in the receiver.List[1, 2, 3, 4].minItem({ arg item, i; item + 10 });

.maxIndex(function)

Answer the index of the maximum of the results of function evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index. If function is nil, then answer the maximum of all items in the receiver.List[1, 2, 3, 4].maxIndex({ arg item, i; item + 10 }); [3.2, 12.2, 13, 0.4].maxIndex;

.minIndex(function)

Answer the index of the minimum of the results of function evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index. If function is nil, then answer the minimum of all items in the receiver.List[1, 2, 3, 4].minIndex({ arg item, i; item + 10 }); List[3.2, 12.2, 13, 0.4].minIndex;

.maxSizeAtDepth(rank)

Returns the maximum size of all subcollections at a certain depth (dimension)

Arguments:

rank

The depth at which the size of the collection is measuredSet[Set[1, 2, 3], [Set[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(2); Set[Set[1, 2, 3], [Set[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(1); Set[Set[1, 2, 3], [Set[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(0); Set[].maxSizeAtDepth(0); Set[[]].maxSizeAtDepth(0); Set[[]].maxSizeAtDepth(1);

.maxDepth(max: 1)

Returns the maximum depth of all subcollections.

Arguments:

max	Internally used only.Set[Set[1, 2, 3], Set[Set[41, 52], 5, 6], 1, 2, 3].maxDepth

.iter

Returns a Routine that returns the elements one by one.r = Set[10, 2, -3, -4].iter; r.next; r.next; r.next; r.next; // nil.

Conversion

.asBag

Answer a Bag to which all items in the receiver have been added.List[1, 2, 3, 4].asBag;

.asList

Answer a List to which all items in the receiver have been added.Set[1, 2, 3, 4].asList;

.asSet

Answer a Set to which all items in the receiver have been added.List[1, 2, 3, 4].asSet;

.asSortedList(function)

Answer a SortedList to which all items in the receiver have been added.List[2, 1, 4, 3].asSortedList;

.asDict(mergeFunc, class)

Answer a corresponding dictionary. This is part of the Key Value Pairs interface.

Arguments:

mergeFunc	Use this function to decide what to do with duplicate keys.
class	The class of the dictionary to be returned. By default this is an IdentityDictionary.

.asAssociations(class)

Answer an array of Associations. If the first item of the list is already an associiation, return itself. 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.

.asPairs(class)

Answer an array with 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.

.asEvent(mergeFunc)

Answer an Event: with the key value pairs. See Key Value Pairs.

.asDictWith(mergeFunc, class)

used internally by asDict.

.powerset

Returns all possible combinations of the collection's elements.Set[1, 2, 3].powerset; // generate the von neumann ordinals. (warning: only count to four at maximum!) a = Set[]; a = a.powerset; a = a.powerset; a = a.powerset; u = { |set| set.unify }; // union (count down) n = { |set| set.powerset }; // powerset (count up) a = Set[]; // empty set (zero) n.(n.(a)); // two u.(n.(n.(a))) == n.(a); // two - one == one u.(u.(n.(n.(a)))) == u.(n.(a)); // two - two == one - one

.flopDict(unbubble: true)

Takes a collection of dictionaries and returns a single dictionary with arrays of all dictionaries' elements. If unbubble is True (default), and if one element is singular, the array is replaced by this element.[(degree: 7, x: 4), (degree: 8, x: 5), (degree: -2, dur: 2.5)].flopDict; [(degree: 7, x: 4), (degree: 8, x: 5), (degree: -2, dur: 2.5)].flopDict(false);

.histo(steps: 100, min, max)

Returns a histogram of the collection by counting the number of values that fall into each slot of size (default: 100) subdivisions between min and max. If there are any values outside this range, it posts a note. If min or max is not given, the smallest (or largest value respectively) is used.{ 1.0.linrand }.dup(10000).histo(1000).plot; { 8.rand }.dup(10000).histo(8).plot(discrete: true);

.invert(axis)

Subtractively invert a collection about a value (default: sum of minimal and maximum value). It can be used to invert a pitch list about a given axis.[0, 1, 4, 7].invert(0); [0, 1, 2, 3].invert(1); [3, 2, 9, 7].invert(11); // becomes [ 19, 20, 13, 15 ] // if axis is nil, invert uses the registral center [3, 2, 9, 7].invert; // becomes [ 8, 9, 2, 4 ] // invert chords [[0, 5, 7], [5, 7, 11], [6, 7, 9]].invert(5);

Writing to streams

.printOn(stream)

Print a representation of the collection to a stream.

.storeOn(stream)

Write a compilable representation of the collection to a stream.

.printItemsOn(stream)

Print a comma separated compilable representation of the items in the collection to a stream.

.storeItemsOn(stream)

Write a comma separated compilable representation of the items in the collection to a stream.

Set specific operations

.sect(that)

Return the set theoretical intersection of this and that.a = [1, 2, 3]; b = [2, 3, 4, 5]; sect(a, b);

.union(that)

Return the set theoretical union of this and that.a = [1, 2, 3]; b = [2, 3, 4, 5]; union(a, b);

.difference(that)

Return the set of all items which are elements of this, but not of that.a = [1, 2, 3]; b = [2, 3, 4, 5]; difference(a, b);

.symmetricDifference(that)

Return the set of all items which are not elements of both this and that. this -- thata = [1, 2, 3]; b = [2, 3, 4, 5]; symmetricDifference(a, b);

.isSubsetOf(that)

Returns True if all elements of this are also elements of thata = Set[1, 2, 3, 4]; Set[1, 2].isSubsetOf(a); // true Set[1, 5].isSubsetOf(a); // false