HelpSource/Classes/SequenceableCollection.schelp

   1 CLASS::SequenceableCollection
   2 summary::Abstract superclass of integer indexable collections
   3 categories::Collections>Ordered
   4
   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.
   7
   8 CLASSMETHODS::
   9
  10 method::series
  11 Fill a SequenceableCollection with an arithmetic series.
  12 code::
  13 Array.series(5, 10, 2);
  14 ::
  15
  16 method::geom
  17 Fill a SequenceableCollection with a geometric series.
  18 code::
  19 Array.geom(5, 1, 3);
  20 ::
  21
  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
  32
  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 ::
  38
  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 ::
  44
  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 ::
  50
  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 ::
  56
  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 ::
  62
  63 INSTANCEMETHODS::
  64
  65 method::first
  66 Return the first element of the collection.
  67 code::
  68 [3, 4, 5].first;
  69 ::
  70
  71 method::last
  72 Return the last element of the collection.
  73 code::
  74 [3, 4, 5].last;
  75 ::
  76
  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 ::
  83
  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 ::
  90
  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 ::
  96
  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 ::
 104
 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 ::
 111
 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 ::
 118
 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 ::
 125
 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 ::
 131
 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 ::
 138
 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 ::
 144
 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 ::
 157
 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..]::
 161
 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]::
 165
 166 method::remove
 167 Remove strong::item:: from collection.
 168
 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 ::
 176
 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 ::
 184
 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 ::
 192
 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 ::
 198
 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 ::
 204
 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 ::
 211
 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 ::
 219
 220 method::flopWith
 221 Flop with a user defined function. Can be used to collect over several collections in parallel.
 222 code::
 223 [[1, 2, 3], [4, 5, 6]].flopWith(_+_);
 224 [[1, 2, 3], 1, [7, 8]].flopWith{ |a,b,c| a+b+c }; // shorter array wraps
 225
 226 //typical use case
 227 [synths,buffers].flopWith{ |a,b| a.set(\buf,b) }
 228 ::
 229 argument::func
 230 A function taking as many arguments as elements in the array.
 231
 232 method::flopTogether
 233 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.
 234 code::
 235 (
 236 a = flopTogether(
 237         [[1, 2, 3], [4, 5, 6, 7, 8]] * 100,
 238         [[1, 2, 3], [4, 5, 6], [7, 8]],
 239         [1000]
 240 )
 241 );
 242
 243 a.collect(_.size); // sizes are the same
 244 a.collect(_.shape) // shapes can be different
 245 ::
 246
 247 method::resamp0
 248 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver without interpolation.
 249 code::
 250 [1, 2, 3, 4].resamp0(12);
 251 [1, 2, 3, 4].resamp0(2);
 252 ::
 253
 254 method::resamp1
 255 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver with linear interpolation.
 256 code::
 257 [1, 2, 3, 4].resamp1(12);
 258 [1, 2, 3, 4].resamp1(3);
 259 ::
 260
 261 method::choose
 262 Choose an element from the collection at random.
 263 code::
 264 [1, 2, 3, 4].choose;
 265 ::
 266
 267 method::wchoose
 268 Choose an element from the collection at random using a list of probabilities or weights. The weights must sum to 1.0.
 269 code::
 270 [1, 2, 3, 4].wchoose([0.1, 0.2, 0.3, 0.4]);
 271 ::
 272
 273 method::sort
 274 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 }
 275 code::
 276 [6, 2, 1, 7, 5].sort;
 277 [6, 2, 1, 7, 5].sort({ arg a, b; a > b }); // reverse sort
 278 ::
 279
 280 method::sortBy
 281 Sort the contents of the collection using the key strong::key::, which is assumed to be found inside each element of the receiver.
 282 code::
 283 (
 284 a = [
 285         Dictionary[\a->5, \b->1, \c->62],
 286         Dictionary[\a->2, \b->9, \c->65],
 287         Dictionary[\a->8, \b->5, \c->68],
 288         Dictionary[\a->1, \b->3, \c->61],
 289         Dictionary[\a->6, \b->7, \c->63]
 290 ]
 291 )
 292 a.sortBy(\b);
 293 a.sortBy(\c);
 294 ::
 295
 296 method::order
 297 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.
 298 code::
 299 [6, 2, 1, 7, 5].order;
 300 ::
 301
 302 method::swap
 303 Swap two elements in the collection at indices strong::i:: and strong::j::.
 304
 305 method::pairsDo
 306 Calls function for each subsequent pair of elements in the SequentialCollection. The function is passed the two elements and an index.
 307 code::
 308 [1, 2, 3, 4, 5].pairsDo({ arg a, b; [a, b].postln; });
 309 ::
 310
 311 method::doAdjacentPairs
 312 Calls function for every adjacent pair of elements in the SequentialCollection. The function is passed the two adjacent elements and an index.
 313 code::
 314 [1, 2, 3, 4, 5].doAdjacentPairs({ arg a, b; [a, b].postln; });
 315 ::
 316
 317 method::separate
 318 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.
 319 code::
 320 [1, 2, 3, 5, 6, 8, 10].separate({ arg a, b; (b - a) > 1 }).postcs;
 321 ::
 322
 323 method::clump
 324 Separates the collection into sub-collections by separating every groupSize elements.
 325 code::
 326 [1, 2, 3, 4, 5, 6, 7, 8].clump(3).postcs;
 327 ::
 328
 329 method::clumps
 330 Separates the collection into sub-collections by separating elements into groupings whose size is given by integers in the groupSizeList.
 331 code::
 332 [1, 2, 3, 4, 5, 6, 7, 8].clumps([1, 2]).postcs;
 333 ::
 334
 335 method::curdle
 336 Separates the collection into sub-collections by separating elements according to the given probability.
 337 code::
 338 [1, 2, 3, 4, 5, 6, 7, 8].curdle(0.3).postcs;
 339 ::
 340
 341 method::integrate
 342 Returns a collection with the incremental sums of all elements.
 343 code::
 344 [3, 4, 1, 1].integrate;
 345 ::
 346
 347 method::differentiate
 348 Returns a collection with the pairwise difference between all elements.
 349 code::
 350 [3, 4, 1, 1].differentiate;
 351 ::
 352
 353 method::reduce
 354 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.
 355 code::
 356 [3, 4, 5, 6].reduce('*'); // this is the same as [3, 4, 5, 6].product
 357 [3, 4, 5, 6].reduce(\lcm); // Lowest common multiple of the whole set of numbers
 358 ["d", "e", (0..9), "h"].reduce('++'); // concatenation
 359 [3, 4, 5, 6].reduce({ |a, b| sin(a) * sin(b) }); // product of sines
 360 ::
 361 argument::operator
 362 may be a link::Classes/Function:: or a link::Classes/Symbol::.
 363
 364 method::convertDigits
 365 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.
 366 code::
 367 [1, 0, 0, 0].convertDigits;
 368 [1, 0, 0, 0].convertDigits(2);
 369 [1, 0, 0, 0].convertDigits(3);
 370 ::
 371
 372 method::hammingDistance
 373 Returns the count of array elements that are not equal in identical positions. http://en.wikipedia.org/wiki/Hamming_distance
 374
 375 The collections are not wrapped - if one array is shorter than the other, the difference in size should be included in the count.
 376 code::
 377 [0, 0, 0, 1, 1, 1, 0, 1, 0, 0].hammingDistance([0, 0, 1, 1, 0, 0, 0, 0, 1, 1]);
 378 "SuperMan".hammingDistance("SuperCollider");
 379 ::
 380
 381 subsection::Math Support - Unary Messages
 382
 383 All of the following messages send the message link::#-performUnaryOp:: to the receiver with the unary message selector as an argument.
 384
 385 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
 386
 387 method::performUnaryOp
 388 Creates a new collection of the results of applying the selector to all elements in the receiver.
 389 code::
 390 [1, 2, 3, 4].neg;
 391 [1, 2, 3, 4].reciprocal;
 392 ::
 393
 394 subsection::Math Support - Binary Messages
 395
 396 All of the following messages send the message link::#-performBinaryOp:: to the receiver with the binary message selector and the second operand as arguments.
 397
 398 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
 399
 400 method::performBinaryOp
 401 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.
 402 code::
 403 ([1, 2, 3, 4] * 10);
 404 ([1, 2, 3, 4] * [4, 5, 6, 7]);
 405 ::
 406
 407 subsection::Multichannel wrappers
 408 All of the following messages are performed on the elements of this collection, using link::Classes/Object#-multiChannelPerform::.
 409
 410 The result depends on the objects in the collection, but the main use case is for link::Classes/UGen::s.
 411
 412 See also link::Guides/Multichannel-Expansion::
 413
 414 method::clip, wrap, fold, prune, linlin, linexp, explin, expexp, lincurve, curvelin, range, exprange, unipolar, bipolar, lag, lag2, lag3, lagud, lag2ud, lag3ud, varlag, slew, blend, checkBadValues
 415 Calls code:: this.multiChannelPerform(selector, *args) :: where selector is the name of the message.
 416
 417
 418 subsection:: Rhythm-lists
 419 method:: convertRhythm
 420 Convert a rhythm-list to durations.
 421 discussion::
 422 supports a variation of Mikael Laurson's rhythm list RTM-notation. footnote::
 423 see Laurson and Kuuskankare's 2003, "From RTM-notation to ENP-score-notation"
 424 http://jim2003.agglo-montbeliard.fr/articles/laurson.pdf
 425 ::
 426
 427 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.
 428
 429 If the divisions in the rtm-list are events, the event durations are interpreted as relative durations, and a list of events is returned.
 430 code::
 431 // using numbers as score
 432 [3, [1, 2, 1], 1].convertRhythm; // List[ 0.75, 1.5, 0.75 ]
 433 [2, [1, 3, [1, [2, 1, 1, 1]], 1, 3], 1].convertRhythm;
 434 [2, [1, [1, [2, 1, 1, 1]]], 1].convertRhythm;
 435 [2, [1, [1, [2, 1, 1, 1]]], 2].convertRhythm; // repeat
 436 [2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm; // negative value is tied over.
 437
 438 // sound example
 439 Pbind(\degree, Pseries(0, 1, inf), \dur, Pseq([2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm)).play;
 440 ::
 441