| blob | 22e4ad2c86ce471d131c1aadb120083eb4db95bc |
1 CLASS::SequenceableCollection
2 summary::Abstract superclass of integer indexable collections
3 categories::Collections>Ordered
5 DESCRIPTION::
6 SequenceableCollection is a subclass of Collection whose elements can be indexed by an Integer. It has many useful subclasses; link::Classes/Array:: and link::Classes/List:: are amongst the most commonly used.
8 CLASSMETHODS::
10 method::series
11 Fill a SequenceableCollection with an arithmetic series.
12 code::
13 Array.series(5, 10, 2);
14 ::
16 method::geom
17 Fill a SequenceableCollection with a geometric series.
18 code::
19 Array.geom(5, 1, 3);
20 ::
22 method::fib
23 Fill a SequenceableCollection with a fibonacci series.
24 code::
25 Array.fib(5);
26 Array.fib(5, 2, 32); // start from 32 with step 2.
27 ::
28 argument::a
29 the starting step value
30 argument::b
31 the starting value
33 method::rand
34 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal::.
35 code::
36 Array.rand(8, 1, 100);
37 ::
39 method::rand2
40 Fill a SequenceableCollection with random values in the range -strong::val:: to +strong::val::.
41 code::
42 Array.rand2(8, 100);
43 ::
45 method::linrand
46 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal:: with a linear distribution.
47 code::
48 Array.linrand(8, 1, 100);
49 ::
51 method::exprand
52 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal:: with exponential distribution.
53 code::
54 Array.exprand(8, 1, 100);
55 ::
57 method::interpolation
58 Fill a SequenceableCollection with the interpolated values between the strong::start:: and strong::end:: values.
59 code::
60 Array.interpolation(5, 3.2, 20.5);
61 ::
63 INSTANCEMETHODS::
65 method::first
66 Return the first element of the collection.
67 code::
68 [3, 4, 5].first;
69 ::
71 method::last
72 Return the last element of the collection.
73 code::
74 [3, 4, 5].last;
75 ::
77 method::putFirst, putLast
78 Place strong::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.
79 code::
80 [3, 4, 5].putFirst(100);
81 [3, 4, 5].putLast(100);
82 ::
84 method::indexOf
85 Return the index of an strong::item:: in the collection, or nil if not found.
86 code::
87 [3, 4, 100, 5].indexOf(100);
88 [3, 4, \foo, \bar].indexOf(\foo);
89 ::
91 method::indexOfEqual
92 Return the index of something in the collection that equals the strong::item::, or nil if not found.
93 code::
94 [3, 4, "foo", "bar"].indexOfEqual("foo");
95 ::
97 method::indicesOfEqual
98 Return an array of indices of things in the collection that equal the strong::item::, or nil if not found.
99 code::
100 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
101 y.indicesOfEqual(7);
102 y.indicesOfEqual(5);
103 ::
105 method::indexOfGreaterThan
106 Return the first index containing an strong::item:: which is greater than strong::item::.
107 code::
108 y = List[ 10, 5, 77, 55, 12, 123];
109 y.indexOfGreaterThan(70);
110 ::
112 method::find
113 If the strong::sublist:: exists in the receiver (in the specified order), at an offset greater than or equal to the initial strong::offset::, then return the starting index.
114 code::
115 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
116 y.find([7, 6, 5]);
117 ::
119 method::findAll
120 Similar to link::#-find:: but returns an array of all the indices at which the sequence is found.
121 code::
122 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
123 y.findAll([7, 6]);
124 ::
126 method::indexIn
127 Returns the closest index of the value in the collection (collection must be sorted).
128 code::
129 [2, 3, 5, 6].indexIn(5.2);
130 ::
132 method::indexInBetween
133 Returns a linearly interpolated float index for the value (collection must be sorted). Inverse operation is link::#-blendAt::.
134 code::
135 x = [2, 3, 5, 6].indexInBetween(5.2);
136 [2, 3, 5, 6].blendAt(x);
137 ::
139 method::blendAt
140 Returns a linearly interpolated value between the two closest indices. Inverse operation is link::#-indexInBetween::.
141 code::
142 x = [2, 5, 6].blendAt(0.4);
143 ::
145 method::copyRange
146 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from strong::start:: to strong::end::.
147 code::x.copyRange(a, b):: can also be written as code::x[a..b]::
148 code::
149 (
150 var y, z;
151 z = [1, 2, 3, 4, 5];
152 y = z.copyRange(1, 3);
153 z.postln;
154 y.postln;
155 )
156 ::
158 method::copyToEnd
159 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from strong::start:: to the end of the collection.
160 code::x.copyToEnd(a):: can also be written as code::x[a..]::
162 method::copyFromStart
163 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from the start of the collection to strong::end::.
164 code::x.copyFromStart(a):: can also be written as code::x[..a]::
166 method::remove
167 Remove strong::item:: from collection.
169 method::take
170 Remove and return strong::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 link::Classes/ArrayedCollection#takeAt::.
171 code::
172 a = [11, 12, 13, 14, 15];
173 a.take(12);
174 a;
175 ::
177 method::keep
178 Keep the first strong::n:: items of the array. If strong::n:: is negative, keep the last -strong::n:: items.
179 code::
180 a = [1, 2, 3, 4, 5];
181 a.keep(3);
182 a.keep(-3);
183 ::
185 method::drop
186 Drop the first strong::n:: items of the array. If strong::n:: is negative, drop the last -strong::n:: items.
187 code::
188 a = [1, 2, 3, 4, 5];
189 a.drop(3);
190 a.drop(-3);
191 ::
193 method::join
194 Returns a link::Classes/String:: formed by connecting all the elements of the receiver, with strong::joiner:: inbetween.
195 code::
196 ["m", "ss", "ss", "pp", ""].join("i");
197 ::
199 method::flat
200 Returns a collection from which all nesting has been flattened.
201 code::
202 [[1, 2, 3], [[4, 5], [[6]]]].flat;
203 ::
205 method::flatten
206 Returns a collection from which strong::numLevels:: of nesting has been flattened.
207 code::
208 [[1, 2, 3], [[4, 5], [[6]]]].flatten(1).postcs;
209 [[1, 2, 3], [[4, 5], [[6]]]].flatten(2).postcs;
210 ::
212 method::flop
213 Invert rows and colums in a two dimensional Collection (turn inside out). See also: link::Classes/Function::.
214 code::
215 [[1, 2, 3], [4, 5, 6]].flop;
216 [[1, 2, 3], [4, 5, 6], [7, 8]].flop; // shorter array wraps
217 [].flop; // result is always 2-d.
218 ::
220 method::flopTogether
221 Invert rows and colums in a an array of dimensional Collections (turn inside out), so that they all match up in size, but remain separated.
222 code::
223 (
224 a = flopTogether(
225 [[1, 2, 3], [4, 5, 6, 7, 8]] * 100,
226 [[1, 2, 3], [4, 5, 6], [7, 8]],
227 [1000]
228 )
229 );
231 a.collect(_.size); // sizes are the same
232 a.collect(_.shape) // shapes can be different
233 ::
235 method::resamp0
236 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver without interpolation.
237 code::
238 [1, 2, 3, 4].resamp0(12);
239 [1, 2, 3, 4].resamp0(2);
240 ::
242 method::resamp1
243 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver with linear interpolation.
244 code::
245 [1, 2, 3, 4].resamp1(12);
246 [1, 2, 3, 4].resamp1(3);
247 ::
249 method::choose
250 Choose an element from the collection at random.
251 code::
252 [1, 2, 3, 4].choose;
253 ::
255 method::wchoose
256 Choose an element from the collection at random using a list of probabilities or weights. The weights must sum to 1.0.
257 code::
258 [1, 2, 3, 4].wchoose([0.1, 0.2, 0.3, 0.4]);
259 ::
261 method::sort
262 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 }
263 code::
264 [6, 2, 1, 7, 5].sort;
265 [6, 2, 1, 7, 5].sort({ arg a, b; a > b }); // reverse sort
266 ::
268 method::sortBy
269 Sort the contents of the collection using the key strong::key::, which is assumed to be found inside each element of the receiver.
270 code::
271 (
272 a = [
273 Dictionary[\a->5, \b->1, \c->62],
274 Dictionary[\a->2, \b->9, \c->65],
275 Dictionary[\a->8, \b->5, \c->68],
276 Dictionary[\a->1, \b->3, \c->61],
277 Dictionary[\a->6, \b->7, \c->63]
278 ]
279 )
280 a.sortBy(\b);
281 a.sortBy(\c);
282 ::
284 method::order
285 Return an array of indices that would sort the collection into order. strong::function:: is treated the same way as for the link::#-sort:: method.
286 code::
287 [6, 2, 1, 7, 5].order;
288 ::
290 method::swap
291 Swap two elements in the collection at indices strong::i:: and strong::j::.
293 method::pairsDo
294 Calls function for each subsequent pair of elements in the SequentialCollection. The function is passed the two elements and an index.
295 code::
296 [1, 2, 3, 4, 5].pairsDo({ arg a, b; [a, b].postln; });
297 ::
299 method::doAdjacentPairs
300 Calls function for every adjacent pair of elements in the SequentialCollection. The function is passed the two adjacent elements and an index.
301 code::
302 [1, 2, 3, 4, 5].doAdjacentPairs({ arg a, b; [a, b].postln; });
303 ::
305 method::separate
306 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.
307 code::
308 [1, 2, 3, 5, 6, 8, 10].separate({ arg a, b; (b - a) > 1 }).postcs;
309 ::
311 method::clump
312 Separates the collection into sub-collections by separating every groupSize elements.
313 code::
314 [1, 2, 3, 4, 5, 6, 7, 8].clump(3).postcs;
315 ::
317 method::clumps
318 Separates the collection into sub-collections by separating elements into groupings whose size is given by integers in the groupSizeList.
319 code::
320 [1, 2, 3, 4, 5, 6, 7, 8].clumps([1, 2]).postcs;
321 ::
323 method::curdle
324 Separates the collection into sub-collections by separating elements according to the given probability.
325 code::
326 [1, 2, 3, 4, 5, 6, 7, 8].curdle(0.3).postcs;
327 ::
329 method::integrate
330 Returns a collection with the incremental sums of all elements.
331 code::
332 [3, 4, 1, 1].integrate;
333 ::
335 method::differentiate
336 Returns a collection with the pairwise difference between all elements.
337 code::
338 [3, 4, 1, 1].differentiate;
339 ::
341 method::reduce
342 Applies the method named by operator to the first and second elements of the collection - then applies the method to the result and to the third element of the collection - then applies the method to the result and to the fourth element of the collection - and so on, until the end of the array.
343 code::
344 [3, 4, 5, 6].reduce('*'); // this is the same as [3, 4, 5, 6].product
345 [3, 4, 5, 6].reduce(\lcm); // Lowest common multiple of the whole set of numbers
346 ["d", "e", (0..9), "h"].reduce('++'); // concatenation
347 [3, 4, 5, 6].reduce({ |a, b| sin(a) * sin(b) }); // product of sines
348 ::
349 argument::operator
350 may be a link::Classes/Function:: or a link::Classes/Symbol::.
352 method::convertDigits
353 Returns an integer resulting from interpreting the elements as digits to a given base (default 10). See also asDigits in link::Classes/Integer#asDigits:: for the complementary method.
354 code::
355 [1, 0, 0, 0].convertDigits;
356 [1, 0, 0, 0].convertDigits(2);
357 [1, 0, 0, 0].convertDigits(3);
358 ::
360 method::hammingDistance
361 Returns the count of array elements that are not equal in identical positions. http://en.wikipedia.org/wiki/Hamming_distance
363 The collections are not wrapped - if one array is shorter than the other, the difference in size should be included in the count.
364 code::
365 [0, 0, 0, 1, 1, 1, 0, 1, 0, 0].hammingDistance([0, 0, 1, 1, 0, 0, 0, 0, 1, 1]);
366 "SuperMan".hammingDistance("SuperCollider");
367 ::
369 subsection::Math Support - Unary Messages
371 All of the following messages send the message link::#-performUnaryOp:: to the receiver with the unary message selector as an argument.
373 method::neg, reciprocal, bitNot, abs, asFloat, asInt, ceil, floor, frac, sign, squared, cubed, sqrt, exp, midicps, cpsmidi, midiratio, ratiomidi, ampdb, dbamp, octcps, cpsoct, log, log2, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, rand, rand2, linrand, bilinrand, sum3rand, distort, softclip, coin, even, odd, isPositive, isNegative, isStrictlyPositive, real, imag, magnitude, magnitudeApx, phase, angle, rho, theta, asFloat, asInteger
375 method::performUnaryOp
376 Creates a new collection of the results of applying the selector to all elements in the receiver.
377 code::
378 [1, 2, 3, 4].neg;
379 [1, 2, 3, 4].reciprocal;
380 ::
382 subsection::Math Support - Binary Messages
384 All of the following messages send the message link::#-performBinaryOp:: to the receiver with the binary message selector and the second operand as arguments.
386 method::+, -, *, /, div, %, **, min, max, <, <=, >, >=, &, |, bitXor, lcm, gcd, round, trunc, atan2, hypot, >>, +>>, ring1, ring2, ring3, ring4, difsqr, sumsqr, sqrdif, absdif, amclip, scaleneg, clip2, excess, <!, rrand, exprand
388 method::performBinaryOp
389 Creates a new collection of the results of applying the selector with the operand to all elements in the receiver. If the operand is a collection then elements of that collection are paired with elements of the receiver.
390 code::
391 ([1, 2, 3, 4] * 10);
392 ([1, 2, 3, 4] * [4, 5, 6, 7]);
393 ::
395 subsection::Multichannel wrappers
396 All of the following messages are performed on the elements of this collection, using link::Classes/Object#-multiChannelPerform::.
398 The result depends on the objects in the collection, but the main use case is for link::Classes/UGen::s.
400 See also link::Guides/Multichannel-Expansion::
402 method::clip, wrap, fold, prune, linlin, linexp, explin, expexp, lincurve, curvelin, range, exprange, unipolar, bipolar, lag, lag2, lag3, lagud, lag2ud, lag3ud, varlag, blend, checkBadValues
403 Calls code:: this.multiChannelPerform(selector, *args) :: where selector is the name of the message.
406 subsection:: Rhythm-lists
407 method:: convertRhythm
408 Convert a rhythm-list to durations.
409 discussion::
410 supports a variation of Mikael Laurson's rhythm list RTM-notation. footnote::
411 see Laurson and Kuuskankare's 2003, "From RTM-notation to ENP-score-notation"
412 http://jim2003.agglo-montbeliard.fr/articles/laurson.pdf
413 ::
415 The method converts a collection of the form code:: [beat-count, [rtm-list], repeats] :: to a link::Classes/List:: of link::Classes/Float::s. A negative integer within the rtm-list equates to a value tied over to the duration following. The method is recursive in that any subdivision within the rtm-list can itself be a nested convertRhythm collection (see example below). The repeats integer has a default value of 1.
417 If the divisions in the rtm-list are events, the event durations are interpreted as relative durations, and a list of events is returned.
418 code::
419 // using numbers as score
420 [3, [1, 2, 1], 1].convertRhythm; // List[ 0.75, 1.5, 0.75 ]
421 [2, [1, 3, [1, [2, 1, 1, 1]], 1, 3], 1].convertRhythm;
422 [2, [1, [1, [2, 1, 1, 1]]], 1].convertRhythm;
423 [2, [1, [1, [2, 1, 1, 1]]], 2].convertRhythm; // repeat
424 [2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm; // negative value is tied over.
426 // sound example
427 Pbind(\degree, Pseries(0, 1, inf), \dur, Pseq([2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm)).play;
428 ::