SuperCollider CLASSES

# SequenceableCollection

Abstract superclass of integer indexable collections
Inherits from: Collection : Object

## Description

SequenceableCollection is a subclass of Collection whose elements can be indexed by an Integer. It has many useful subclasses; Array and List are amongst the most commonly used.

## Class Methods

### *fill (size, function)

From superclass: Collection

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.

### *series (size, start: 0, step: 1)

Fill a SequenceableCollection with an arithmetic series.

Array.series(5, 10, 2);

### *geom (size, start, grow)

Fill a SequenceableCollection with a geometric series.

Array.geom(5, 1, 3);

### *fib (size, a: 0, b: 1)

Fill a SequenceableCollection with a fibonacci series.

Array.fib(5);
Array.fib(5, 2, 32); // start from 32 with step 2.

#### Arguments:

 size the number of values in the collection a the starting step value b the starting value

### *rand (size, minVal, maxVal)

Fill a SequenceableCollection with random values in the range minVal to maxVal.

Array.rand(8, 1, 100);

### *rand2 (size, val)

Fill a SequenceableCollection with random values in the range -val to +val.

Array.rand2(8, 100);

### *linrand (size, minVal, maxVal)

Fill a SequenceableCollection with random values in the range minVal to maxVal with a linear distribution.

Array.linrand(8, 1, 100);

### *exprand (size, minVal, maxVal)

Fill a SequenceableCollection with random values in the range minVal to maxVal with exponential distribution.

Array.exprand(8, 1, 100);

### *interpolation (size, start: 0, end: 1)

Fill a SequenceableCollection with the interpolated values between the start and end values.

Array.interpolation(5, 3.2, 20.5);

## Instance Methods

### -|@| (index)

synonym for ArrayedCollection: -clipAt.

[3, 4, 5]|@|6;

### -@@ (index)

synonym for ArrayedCollection: -wrapAt.

[3, 4, 5]@@6;
[3, 4, 5]@@ -1;
[3, 4, 5]@@[6, 8]

### -@|@ (index)

synonym for ArrayedCollection: -foldAt.

[3, 4, 5]@|@[6, 8];

### -first

Return the first element of the collection.

[3, 4, 5].first;

### -last

Return the last element of the collection.

[3, 4, 5].last;

### -putLast (obj)

Place item at the first / last index in the collection. Note that if the collection is empty (and therefore has no indexed slots) the item will not be added.

[3, 4, 5].putFirst(100);
[3, 4, 5].putLast(100);

### -indexOf (item)

Return the index of an item in the collection, or nil if not found.

[3, 4, 100, 5].indexOf(100);
[3, 4, \foo, \bar].indexOf(\foo);

### -indexOfEqual (item, offset: 0)

Return the index of something in the collection that equals the item, or nil if not found.

[3, 4, "foo", "bar"].indexOfEqual("foo");

### -indicesOfEqual (item)

Return an array of indices of things in the collection that equal the item, or nil if not found.

y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
y.indicesOfEqual(7);
y.indicesOfEqual(5);

### -indexOfGreaterThan (val)

Return the first index containing an item which is greater than item.

y = List[ 10, 5, 77, 55, 12, 123];
y.indexOfGreaterThan(70);

### -selectIndices (function)

Return a new collection of same type as receiver which consists of all indices of those elements of the receiver for which function answers true. The function is passed two arguments, the item and an integer index.

#[a, b, c, g, h, h, j, h].selectIndices({|item, i| item === \h})

If you want to control what type of collection is returned, use -selectIndicesAs

### -selectIndicesAs (function, class)

Return a new collection of type class which consists of all indices of those elements of the receiver for which function answers true. The function is passed two arguments, the item and an integer index.

#[a, b, c, g, h, h, j, h].selectIndicesAs({|item, i| item === \h}, Set)

### -rejectIndices (function)

Return a new collection of same type as receiver which consists of all indices of those elements of the receiver for which function answers false. The function is passed two arguments, the item and an integer index.

#[a, b, c, g, h, h, j, h].rejectIndices({|item, i| item === \h})

If you want to control what type of collection is returned, use -rejectIndicesAs

### -rejectIndicesAs (function, class)

Return a new collection of type class which consists of all indices of those elements of the receiver for which function answers false. The function is passed two arguments, the item and an integer index.

#[a, b, c, g, h, h, j, h].rejectIndicesAs({|item, i| item === \h}, Set)

### -maxIndex (function)

From superclass: Collection

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)

From superclass: Collection

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;

### -find (sublist, offset: 0)

If the sublist exists in the receiver (in the specified order), at an offset greater than or equal to the initial offset, then return the starting index.

y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
y.find([7, 6, 5]);

### -findAll (arr, offset: 0)

Similar to -find but returns an array of all the indices at which the sequence is found.

y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
y.findAll([7, 6]);

### -indexIn (val)

Returns the closest index of the value in the collection (collection must be sorted).

[2, 3, 5, 6].indexIn(5.2);

### -indexInBetween (val)

Returns a linearly interpolated float index for the value (collection must be sorted). Inverse operation is -blendAt.

x = [2, 3, 5, 6].indexInBetween(5.2);
[2, 3, 5, 6].blendAt(x);

### -blendAt (index, method: 'clipAt')

From superclass: Object

Returns a linearly interpolated value between the two closest indices. Inverse operation is -indexInBetween.

x = [2, 5, 6].blendAt(0.4);

### -copyRange (start, end)

Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from start to end. If end < start, an empty collection is returned.

(
var y, z;
z = [1, 2, 3, 4, 5];
y = z.copyRange(1, 3);
z.postln;
y.postln;
)

WARNING: x.copyRange(a, b) is not equivalent to x[a..b]. The latter compiles to ArrayedCollection: -copySeries, which has different behavior when end < start.

### -copyToEnd (start)

Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from start to the end of the collection. x.copyToEnd(a) can also be written as x[a..]

### -copyFromStart (end)

Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from the start of the collection to end. x.copyFromStart(a) can also be written as x[..a]

### -remove (item)

Remove item from collection.

### -take (item)

Remove and return item from collection. The last item in the collection will move to occupy the vacated slot (and the collection size decreases by one). See also takeAt, defined for ArrayedCollection: -takeAt.

a = [11, 12, 13, 14, 15];
a.take(12);
a;

### -obtain (index, default)

Retrieve an element from a given index (like SequenceableCollection: -at). This method is also implemented in Object, so that you can use it in situations where you don't want to know if the receiver is a collection or not. See also: SequenceableCollection: -instill

#### Arguments:

 index The index at which to look for an element default If index exceeds collection size, or receiver is nil, return this instead( a = [10, 20, 30]; b = [10, 20]; c = 7; ); // obtain third element, if outside bounds return 1 a.obtain(2, 1); b.obtain(2, 1); c.obtain(2, 1);

### -instill (index, item, default)

Put an element at a given index (like SequenceableCollection: -put). This method is also implemented in Object, so that you can use it in situations where you don't want to know if the receiver is a collection or not. It will always return a new collection. See also: SequenceableCollection: -obtain

#### Arguments:

 index The index at which to put the item item The object to put into the new collection default If the index exceeds the current collection's size, extend the collection with this element( a = [10, 20, 30, 40]; b = [10, 20]; c = 7; ); a.instill(2, -1); b.instill(2, -1); c.instill(2, -1); // providing a default value c.instill(2, -1, 0);

### -keep (n)

Keep the first n items of the array. If n is negative, keep the last -n items.

a = [1, 2, 3, 4, 5];
a.keep(3);
a.keep(-3);

### -drop (n)

Drop the first n items of the array. If n is negative, drop the last -n items.

a = [1, 2, 3, 4, 5];
a.drop(3);
a.drop(-3);

### -join (joiner)

Returns a String formed by connecting all the elements of the receiver, with joiner inbetween. See also String: -split as the complementary operation.

["m", "ss", "ss", "pp", ""].join("i").postcs;
"mississippi".split("i").postcs;

### -flat

Returns a collection from which all nesting has been flattened.

[[1, 2, 3], [[4, 5], [[6]]]].flat; // [ 1, 2, 3, 4, 5, 6 ]
[1, 2, [3, 4, [5, 6, [7, 8, [9, 0]]]]].flat; // [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 ]

### -flatten (numLevels: 1)

Returns a collection from which numLevels of nesting has been flattened.

#### Arguments:

 numLevels Specifies how many levels downward (inward) to flatten. Zero returns the original.a = [1, 2, [3, 4, [5, 6, [7, 8, [9, 0]]]]]; a.flatten(1); // [ 1, 2, [ 3, 4, [ 5, 6, [ 7, 8, [ 9, 0 ] ] ] ] ] a.flatten(2); // [ 1, 2, 3, 4, 5, 6, [ 7, 8, [ 9, 0 ] ] ] a.flatten(3); // [ 1, 2, 3, 4, 5, 6, 7, 8, [ 9, 0 ] ] a.flatten(4); // [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 ]

### -flatten2 (numLevels: 1)

A symmetric version of -flatten. For a negative numLevels, it flattens starting from the innermost arrays.

#### Arguments:

 numLevels Specifies how many levels downward (inward) or upward (outward) to flatten.a = [1, 2, [3, 4, [5, 6, [7, 8, [9, 0]]]]]; a.flatten2(4); // [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 ] a.flatten2(3); // [ 1, 2, 3, 4, 5, 6, 7, 8, [ 9, 0 ] ] a.flatten2(2); // [ 1, 2, 3, 4, 5, 6, [ 7, 8, [ 9, 0 ] ] ] a.flatten2(1); // [ 1, 2, 3, 4, [ 5, 6, [ 7, 8, [ 9, 0 ] ] ] ] a.flatten2(0); // [ 1, 2, [ 3, 4, [ 5, 6, [ 7, 8, [ 9, 0 ] ] ] ] ] a.flatten2(-1); // [ 1, 2, [ 3, 4, [ 5, 6, [ 7, 8, 9, 0 ] ] ] ] a.flatten2(-2); // [ 1, 2, [ 3, 4, [ 5, 6, 7, 8, 9, 0 ] ] ] a.flatten2(-3); // [ 1, 2, [ 3, 4, 5, 6, 7, 8, 9, 0 ] ] a.flatten2(-4); // [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 ]

### -flatBelow (level: 1)

Flatten all subarrays deeper than level.

#### Arguments:

 level Specifies from what level onward to flatten. level 0 is outermost, so flatBelow(0) is like flat.a = [1, 2, [3, 4, [5, 6, [7, 8, [9, 0]]]]]; a.flatBelow(0); // [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 ] a.flatBelow(1); // [ 1, 2, [ 3, 4, 5, 6, 7, 8, 9, 0 ] ] a.flatBelow(2); // [ 1, 2, [ 3, 4, [ 5, 6, 7, 8, 9, 0 ] ] ] // to set the level below which to flatten from the deepest level up, // one can use coll.maxDepth. E.g. to flatten only the innermost level: a.flatBelow( (a.maxDepth - 1) - 1); // for lowest two levels: a.flatBelow( (a.maxDepth - 1) - 2);

### -flop

Invert rows and columns in a two dimensional Collection (turn inside out). See also: Function.

[[1, 2, 3], [4, 5, 6]].flop;
[[1, 2, 3], [4, 5, 6], [7, 8]].flop; // shorter array wraps
[].flop; // result is always 2-d.

Note that the innermost arrays are not copied:

a = [1, 2];
x = [[[a, 5], [a, 10]], [[a, 50, 60]]].flop;
a[0] = pi;
x // pi is everywhere

### -flopWith (func)

Flop with a user defined function. Can be used to collect over several collections in parallel.

[[1, 2, 3], [4, 5, 6]].flopWith(_+_);
[[1, 2, 3], 1, [7, 8]].flopWith{ |a,b,c| a+b+c }; // shorter array wraps

// typical use case (pseudocode)
[synths, buffers].flopWith{ |a,b| a.set(\buf, b) }

#### Arguments:

 func A function taking as many arguments as elements in the array.

### -flopTogether ( ... moreArrays)

Invert rows and columns in a an array of dimensional Collections (turn inside out), so that they all match up in size, but remain separated.

(
a = flopTogether(
[[1, 2, 3], [4, 5, 6, 7, 8]] * 100,
[[1, 2, 3], [4, 5, 6], [7, 8]],
[1000]
)
);

a.collect(_.size); // sizes are the same
a.collect(_.shape) // shapes can be different

### -flopDeep (rank)

Fold dimensions in a multi-dimensional Collection (turn inside out).

#### Arguments:

 rank The depth (dimension) from which the array is inverted inside-out.[[1, 2, 3], [[41, 52], 5, 6]].flopDeep(2); [[1, 2, 3], [[41, 52], 5, 6]].flopDeep(1); [[1, 2, 3], [[41, 52], 5, 6]].flopDeep(0); [[1, 2, 3], [[41, 52], 5, 6]].flopDeep; // without argument, flop from the deepest level [[[10, 100, 1000], 2, 3], [[41, 52], 5, 6]].flopDeep(2); // shorter array wraps [].flopDeep(1); // result is always one dimension higher. [[]].flopDeep(4); NOTE: Note that, just like in flop, the innermost arrays (deeper than rank) are not copied.a = [1, 2]; x = [[[a, 5], [a, 10]], [[a, 50, 60]]].flopDeep(1); a[0] = pi; x // pi is everywhere

### -maxSizeAtDepth (rank)

From superclass: Collection

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

#### Arguments:

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

### -maxDepth (max: 1)

From superclass: Collection

Returns the maximum depth of all subarrays.

#### Arguments:

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

### -isSeries (step)

Returns true if the collection is an arithmetic series.

#### Arguments:

 step Step size to look for. If none is given, any step size will match.[ 0, 1, 2, 3, 4, 5 ].isSeries; // true [ 1.5, 2.5, 3.5, 4.5, 5.5, 6.5 ].isSeries; // true [ 0, 1, 4, 5 ].isSeries; // false [ 0, 3, 6, 9, 12, 15 ].isSeries; // true [ 0, 3, 6, 9, 12, 15 ].isSeries(1); // false [ 2 ] // true [ ] // true (empty sequence)

### -resamp0 (newSize)

Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver without interpolation.

[1, 2, 3, 4].resamp0(12);
[1, 2, 3, 4].resamp0(2);

### -resamp1 (newSize)

Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver with linear interpolation.

[1, 2, 3, 4].resamp1(12);
[1, 2, 3, 4].resamp1(3);

### -choose

Choose an element from the collection at random.

[1, 2, 3, 4].choose;

### -wchoose (weights)

Choose an element from the collection at random using a list of probabilities or weights. The weights must sum to 1.0.

[1, 2, 3, 4].wchoose([0.1, 0.2, 0.3, 0.4]);

### -sort (function)

Sort the contents of the collection using the comparison function argument. The function should take two elements as arguments and return true if the first argument should be sorted before the second argument. If the function is nil, the following default function is used. { arg a, b; a < b }

[6, 2, 1, 7, 5].sort;
[6, 2, 1, 7, 5].sort({ arg a, b; a > b }); // reverse sort

### -sortBy (key)

Sort the contents of the collection using the key key, which is assumed to be found inside each element of the receiver.

(
a = [
Dictionary[\a->5, \b->1, \c->62],
Dictionary[\a->2, \b->9, \c->65],
Dictionary[\a->8, \b->5, \c->68],
Dictionary[\a->1, \b->3, \c->61],
Dictionary[\a->6, \b->7, \c->63]
]
)
a.sortBy(\b);
a.sortBy(\c);

### -order (function)

Return an array of indices that would sort the collection into order. function is treated the same way as for the -sort method.

[6, 2, 1, 7, 5].order;

### -swap (i, j)

Swap two elements in the collection at indices i and j.

### -pairsDo (function)

Calls function for each subsequent pair of elements in the SequentialCollection. The function is passed the two elements and an index.

[1, 2, 3, 4, 5].pairsDo({ arg a, b; [a, b].postln; });

Calls function for every adjacent pair of elements in the SequentialCollection. The function is passed the two adjacent elements and an index.

[1, 2, 3, 4, 5].doAdjacentPairs({ arg a, b; [a, b].postln; });

### -separate (function: true)

Separates the collection into sub-collections by calling the function for each adjacent pair of elements. If the function returns true, then a separation is made between the elements.

[1, 2, 3, 5, 6, 8, 10].separate({ arg a, b; (b - a) > 1 }).postcs;