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 copymethod:: Collection *fill
  11
  12 method::series
  13 Fill a SequenceableCollection with an arithmetic series.
  14 code::
  15 Array.series(5, 10, 2);
  16 ::
  17
  18 method::geom
  19 Fill a SequenceableCollection with a geometric series.
  20 code::
  21 Array.geom(5, 1, 3);
  22 ::
  23
  24 method::fib
  25 Fill a SequenceableCollection with a fibonacci series.
  26 code::
  27 Array.fib(5);
  28 Array.fib(5, 2, 32); // start from 32 with step 2.
  29 ::
  30 argument::size
  31 the number of values in the collection
  32 argument::a
  33 the starting step value
  34 argument::b
  35 the starting value
  36
  37 method::rand
  38 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal::.
  39 code::
  40 Array.rand(8, 1, 100);
  41 ::
  42
  43 method::rand2
  44 Fill a SequenceableCollection with random values in the range -strong::val:: to +strong::val::.
  45 code::
  46 Array.rand2(8, 100);
  47 ::
  48
  49 method::linrand
  50 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal:: with a linear distribution.
  51 code::
  52 Array.linrand(8, 1, 100);
  53 ::
  54
  55 method::exprand
  56 Fill a SequenceableCollection with random values in the range strong::minVal:: to strong::maxVal:: with exponential distribution.
  57 code::
  58 Array.exprand(8, 1, 100);
  59 ::
  60
  61 method::interpolation
  62 Fill a SequenceableCollection with the interpolated values between the strong::start:: and strong::end:: values.
  63 code::
  64 Array.interpolation(5, 3.2, 20.5);
  65 ::
  66
  67
  68
  69 INSTANCEMETHODS::
  70
  71
  72 method::|@|
  73 synonym for link::Classes/ArrayedCollection#-clipAt::.
  74 code::
  75 [3, 4, 5]|@|6;
  76 ::
  77
  78 method::@@
  79 synonym for link::Classes/ArrayedCollection#-wrapAt::.
  80 code::
  81 [3, 4, 5]@@6;
  82 [3, 4, 5]@@ -1;
  83 [3, 4, 5]@@[6, 8]
  84 ::
  85
  86 method::@|@
  87 synonym for link::Classes/ArrayedCollection#-foldAt::.
  88 code::
  89 [3, 4, 5]@|@[6, 8];
  90 ::
  91
  92 method::first
  93 Return the first element of the collection.
  94 code::
  95 [3, 4, 5].first;
  96 ::
  97
  98 method::last
  99 Return the last element of the collection.
 100 code::
 101 [3, 4, 5].last;
 102 ::
 103
 104 method::putFirst, putLast
 105 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.
 106 code::
 107 [3, 4, 5].putFirst(100);
 108 [3, 4, 5].putLast(100);
 109 ::
 110
 111 method::indexOf
 112 Return the index of an strong::item:: in the collection, or nil if not found.
 113 code::
 114 [3, 4, 100, 5].indexOf(100);
 115 [3, 4, \foo, \bar].indexOf(\foo);
 116 ::
 117
 118 method::indexOfEqual
 119 Return the index of something in the collection that equals the strong::item::, or nil if not found.
 120 code::
 121 [3, 4, "foo", "bar"].indexOfEqual("foo");
 122 ::
 123
 124 method::indicesOfEqual
 125 Return an array of indices of things in the collection that equal the strong::item::, or nil if not found.
 126 code::
 127 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
 128 y.indicesOfEqual(7);
 129 y.indicesOfEqual(5);
 130 ::
 131
 132 method::indexOfGreaterThan
 133 Return the first index containing an strong::item:: which is greater than strong::item::.
 134 code::
 135 y = List[ 10, 5, 77, 55, 12, 123];
 136 y.indexOfGreaterThan(70);
 137 ::
 138
 139 copymethod:: Collection -maxIndex
 140
 141 copymethod:: Collection -minIndex
 142
 143
 144 method::find
 145 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.
 146 code::
 147 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
 148 y.find([7, 6, 5]);
 149 ::
 150
 151 method::findAll
 152 Similar to link::#-find:: but returns an array of all the indices at which the sequence is found.
 153 code::
 154 y = [7, 8, 7, 6, 5, 6, 7, 6, 7, 8, 9];
 155 y.findAll([7, 6]);
 156 ::
 157
 158 method::indexIn
 159 Returns the closest index of the value in the collection (collection must be sorted).
 160 code::
 161 [2, 3, 5, 6].indexIn(5.2);
 162 ::
 163
 164 method::indexInBetween
 165 Returns a linearly interpolated float index for the value (collection must be sorted). Inverse operation is link::#-blendAt::.
 166 code::
 167 x = [2, 3, 5, 6].indexInBetween(5.2);
 168 [2, 3, 5, 6].blendAt(x);
 169 ::
 170
 171 method::blendAt
 172 Returns a linearly interpolated value between the two closest indices. Inverse operation is link::#-indexInBetween::.
 173 code::
 174 x = [2, 5, 6].blendAt(0.4);
 175 ::
 176
 177 method::copyRange
 178 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from strong::start:: to strong::end::.
 179 code::x.copyRange(a, b):: can also be written as code::x[a..b]::
 180 code::
 181 (
 182 var y, z;
 183 z = [1, 2, 3, 4, 5];
 184 y = z.copyRange(1, 3);
 185 z.postln;
 186 y.postln;
 187 )
 188 ::
 189
 190 method::copyToEnd
 191 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from strong::start:: to the end of the collection.
 192 code::x.copyToEnd(a):: can also be written as code::x[a..]::
 193
 194 method::copyFromStart
 195 Return a new SequenceableCollection which is a copy of the indexed slots of the receiver from the start of the collection to strong::end::.
 196 code::x.copyFromStart(a):: can also be written as code::x[..a]::
 197
 198 method::remove
 199 Remove strong::item:: from collection.
 200
 201 method::take
 202 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::.
 203 code::
 204 a = [11, 12, 13, 14, 15];
 205 a.take(12);
 206 a;
 207 ::
 208
 209 method::keep
 210 Keep the first strong::n:: items of the array. If strong::n:: is negative, keep the last -strong::n:: items.
 211 code::
 212 a = [1, 2, 3, 4, 5];
 213 a.keep(3);
 214 a.keep(-3);
 215 ::
 216
 217 method::drop
 218 Drop the first strong::n:: items of the array. If strong::n:: is negative, drop the last -strong::n:: items.
 219 code::
 220 a = [1, 2, 3, 4, 5];
 221 a.drop(3);
 222 a.drop(-3);
 223 ::
 224
 225 method::join
 226 Returns a link::Classes/String:: formed by connecting all the elements of the receiver, with strong::joiner:: inbetween. See also link::Classes/String#-split:: as the complementary operation.
 227 code::
 228 ["m", "ss", "ss", "pp", ""].join("i").postcs;
 229 "mississippi".split("i").postcs;
 230 ::
 231
 232 method::flat
 233 Returns a collection from which all nesting has been flattened.
 234 code::
 235 [[1, 2, 3], [[4, 5], [[6]]]].flat;
 236 ::
 237
 238 method::flatten
 239 Returns a collection from which strong::numLevels:: of nesting has been flattened.
 240 code::
 241 [[1, 2, 3], [[4, 5], [[6]]]].flatten(1).postcs;
 242 [[1, 2, 3], [[4, 5], [[6]]]].flatten(2).postcs;
 243 ::
 244
 245 method::flop
 246 Invert rows and colums in a two dimensional Collection (turn inside out). See also: link::Classes/Function::.
 247 code::
 248 [[1, 2, 3], [4, 5, 6]].flop;
 249 [[1, 2, 3], [4, 5, 6], [7, 8]].flop; // shorter array wraps
 250 [].flop; // result is always 2-d.
 251 ::
 252 Note that the innermost arrays are not copied:
 253 code::
 254 a = [1, 2];
 255 x = [[[a, 5], [a, 10]], [[a, 50, 60]]].flop;
 256 a[0] = pi;
 257 x // pi is everywhere
 258 ::
 259
 260
 261 method::flopWith
 262 Flop with a user defined function. Can be used to collect over several collections in parallel.
 263 code::
 264 [[1, 2, 3], [4, 5, 6]].flopWith(_+_);
 265 [[1, 2, 3], 1, [7, 8]].flopWith{ |a,b,c| a+b+c }; // shorter array wraps
 266
 267 // typical use case (pseudocode)
 268 [synths, buffers].flopWith{ |a,b| a.set(\buf, b) }
 269 ::
 270 argument::func
 271 A function taking as many arguments as elements in the array.
 272
 273 method::flopTogether
 274 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.
 275 code::
 276 (
 277 a = flopTogether(
 278         [[1, 2, 3], [4, 5, 6, 7, 8]] * 100,
 279         [[1, 2, 3], [4, 5, 6], [7, 8]],
 280         [1000]
 281 )
 282 );
 283
 284 a.collect(_.size); // sizes are the same
 285 a.collect(_.shape) // shapes can be different
 286 ::
 287
 288
 289 method::flopDeep
 290 Fold dimensions in a multi-dimensional Collection (turn inside out).
 291
 292 argument::rank
 293 The depth (dimension) from which the array is inverted inside-out.
 294
 295 code::
 296 [[1, 2, 3], [[41, 52], 5, 6]].flopDeep(2);
 297 [[1, 2, 3], [[41, 52], 5, 6]].flopDeep(1);
 298 [[1, 2, 3], [[41, 52], 5, 6]].flopDeep(0);
 299 [[1, 2, 3], [[41, 52], 5, 6]].flopDeep; // without argument, flop from the deepest level
 300
 301 [[[10, 100, 1000], 2, 3], [[41, 52], 5, 6]].flopDeep(2); // shorter array wraps
 302 [].flopDeep(1); // result is always one dimension higher.
 303 [[]].flopDeep(4);
 304 ::
 305
 306 note::Note that, just like in flop, the innermost arrays (deeper than rank) are not copied.::
 307
 308 code::
 309 a = [1, 2];
 310 x = [[[a, 5], [a, 10]], [[a, 50, 60]]].flopDeep(1);
 311 a[0] = pi;
 312 x // pi is everywhere
 313 ::
 314
 315 method::maxSizeAtDepth
 316 Returns the maximum size of all subarrays at a certain depth (dimension)
 317
 318 argument::rank
 319 The depth at which the size of the arrays is measured
 320
 321 code::
 322 [[1, 2, 3], [[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(2);
 323 [[1, 2, 3], [[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(1);
 324 [[1, 2, 3], [[41, 52], 5, 6], 1, 2, 3].maxSizeAtDepth(0);
 325 [].maxSizeAtDepth(0);
 326 [[]].maxSizeAtDepth(0);
 327 [[]].maxSizeAtDepth(1);
 328 ::
 329
 330 method::maxDepth
 331 Returns the maximum depth of all subarrays.
 332
 333 argument::max
 334 Internally used only.
 335
 336 code::
 337 [[1, 2, 3], [[41, 52], 5, 6], 1, 2, 3].maxDepth
 338 ::
 339
 340 method::resamp0
 341 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver without interpolation.
 342 code::
 343 [1, 2, 3, 4].resamp0(12);
 344 [1, 2, 3, 4].resamp0(2);
 345 ::
 346
 347 method::resamp1
 348 Returns a new Collection of the desired length, with values resampled evenly-spaced from the receiver with linear interpolation.
 349 code::
 350 [1, 2, 3, 4].resamp1(12);
 351 [1, 2, 3, 4].resamp1(3);
 352 ::
 353
 354 method::choose
 355 Choose an element from the collection at random.
 356 code::
 357 [1, 2, 3, 4].choose;
 358 ::
 359
 360 method::wchoose
 361 Choose an element from the collection at random using a list of probabilities or weights. The weights must sum to 1.0.
 362 code::
 363 [1, 2, 3, 4].wchoose([0.1, 0.2, 0.3, 0.4]);
 364 ::
 365
 366 method::sort
 367 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 }
 368 code::
 369 [6, 2, 1, 7, 5].sort;
 370 [6, 2, 1, 7, 5].sort({ arg a, b; a > b }); // reverse sort
 371 ::
 372
 373 method::sortBy
 374 Sort the contents of the collection using the key strong::key::, which is assumed to be found inside each element of the receiver.
 375 code::
 376 (
 377 a = [
 378         Dictionary[\a->5, \b->1, \c->62],
 379         Dictionary[\a->2, \b->9, \c->65],
 380         Dictionary[\a->8, \b->5, \c->68],
 381         Dictionary[\a->1, \b->3, \c->61],
 382         Dictionary[\a->6, \b->7, \c->63]
 383 ]
 384 )
 385 a.sortBy(\b);
 386 a.sortBy(\c);
 387 ::
 388
 389 method::order
 390 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.
 391 code::
 392 [6, 2, 1, 7, 5].order;
 393 ::
 394
 395 method::swap
 396 Swap two elements in the collection at indices strong::i:: and strong::j::.
 397
 398 method::pairsDo
 399 Calls function for each subsequent pair of elements in the SequentialCollection. The function is passed the two elements and an index.
 400 code::
 401 [1, 2, 3, 4, 5].pairsDo({ arg a, b; [a, b].postln; });
 402 ::
 403
 404 method::doAdjacentPairs
 405 Calls function for every adjacent pair of elements in the SequentialCollection. The function is passed the two adjacent elements and an index.
 406 code::
 407 [1, 2, 3, 4, 5].doAdjacentPairs({ arg a, b; [a, b].postln; });
 408 ::
 409
 410 method::separate
 411 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.
 412 code::
 413 [1, 2, 3, 5, 6, 8, 10].separate({ arg a, b; (b - a) > 1 }).postcs;
 414 ::
 415
 416 method::split
 417 Separates the collection into sub-collections at the separator element or subarray. The separator is a link::Classes/Collection::, or anything that can be converted into the class this method is called on. It is strong::not:: included in the output array. The default separator is $/, for the common use in link::Classes/String::.
 418 code::
 419 [1, 2, 1, 2, 3, 1, 2, 1, 3].split([2, 1])
 420 ::
 421
 422 method::clump
 423 Separates the collection into sub-collections by separating every groupSize elements.
 424 code::
 425 [1, 2, 3, 4, 5, 6, 7, 8].clump(3).postcs;
 426 ::
 427
 428 method::clumps
 429 Separates the collection into sub-collections by separating elements into groupings whose size is given by integers in the groupSizeList.
 430 code::
 431 [1, 2, 3, 4, 5, 6, 7, 8].clumps([1, 2]).postcs;
 432 ::
 433
 434 method::curdle
 435 Separates the collection into sub-collections by randomly separating elements according to the given probability.
 436 code::
 437 [1, 2, 3, 4, 5, 6, 7, 8].curdle(0.3).postcs;
 438 ::
 439
 440 method::integrate
 441 Returns a collection with the incremental sums of all elements.
 442 code::
 443 [3, 4, 1, 1].integrate;
 444 ::
 445
 446 method::differentiate
 447 Returns a collection with the pairwise difference between all elements.
 448 code::
 449 [3, 4, 1, 1].differentiate;
 450 ::
 451
 452 method::reduce
 453 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.
 454 code::
 455 [3, 4, 5, 6].reduce('*'); // this is the same as [3, 4, 5, 6].product
 456 [3, 4, 5, 6].reduce(\lcm); // Lowest common multiple of the whole set of numbers
 457 ["d", "e", (0..9), "h"].reduce('++'); // concatenation
 458 [3, 4, 5, 6].reduce({ |a, b| sin(a) * sin(b) }); // product of sines
 459 ::
 460 argument::operator
 461 may be a link::Classes/Function:: or a link::Classes/Symbol::.
 462
 463 method::convertDigits
 464 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.
 465 code::
 466 [1, 0, 0, 0].convertDigits;
 467 [1, 0, 0, 0].convertDigits(2);
 468 [1, 0, 0, 0].convertDigits(3);
 469 ::
 470
 471 method::hammingDistance
 472 Returns the count of array elements that are not equal in identical positions. http://en.wikipedia.org/wiki/Hamming_distance
 473
 474 The collections are not wrapped - if one array is shorter than the other, the difference in size should be included in the count.
 475 code::
 476 [0, 0, 0, 1, 1, 1, 0, 1, 0, 0].hammingDistance([0, 0, 1, 1, 0, 0, 0, 0, 1, 1]);
 477 "SuperMan".hammingDistance("SuperCollider");
 478 ::
 479
 480 subsection::Math Support - Unary Messages
 481
 482 All of the following messages send the message link::#-performUnaryOp:: to the receiver with the unary message selector as an argument.
 483
 484 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
 485
 486 method::performUnaryOp
 487 Creates a new collection of the results of applying the selector to all elements in the receiver.
 488 code::
 489 [1, 2, 3, 4].neg;
 490 [1, 2, 3, 4].reciprocal;
 491 ::
 492
 493 subsection::Math Support - Binary Messages
 494
 495 All of the following messages send the message link::#-performBinaryOp:: to the receiver with the binary message selector and the second operand as arguments.
 496
 497 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
 498
 499 method::performBinaryOp
 500 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.
 501 code::
 502 ([1, 2, 3, 4] * 10);
 503 ([1, 2, 3, 4] * [4, 5, 6, 7]);
 504 ::
 505
 506 subsection::Multichannel wrappers
 507 All of the following messages are performed on the elements of this collection, using link::Classes/Object#-multiChannelPerform::.
 508
 509 The result depends on the objects in the collection, but the main use case is for link::Classes/UGen::s.
 510
 511 See also link::Guides/Multichannel-Expansion::
 512
 513 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
 514 Calls code:: this.multiChannelPerform(selector, *args) :: where selector is the name of the message.
 515
 516 method::multichannelExpandRef
 517 This method is called internally on inputs to UGens that take multidimensional arrays, like link::Classes/Klank:: and it allows proper multichannel expansion even in those cases. For SequenceableCollection, this returns the collection itself, assuming that it contains already a number of Refs. See link::Classes/Ref:: for the corresponding method implementation.
 518 argument::rank
 519 The depth at which the list is expanded. For instance the Klank spec has a rank of 2. For more examples, see link::Classes/SequenceableCollection#-flopDeep::
 520 code::
 521 `([[[100, 200], 500], nil, [[[0.01, 0.3], 0.8]]]).multichannelExpandRef(2);
 522 [`[[100, 200], nil, [0.2, 0.8]], `[[130, 202], nil, [0.2, 0.5]]].multichannelExpandRef(2);
 523 ::
 524
 525 subsection:: Rhythm-lists
 526 method:: convertRhythm
 527 Convert a rhythm-list to durations.
 528 discussion::
 529 supports a variation of Mikael Laurson's rhythm list RTM-notation. footnote::
 530 see Laurson and Kuuskankare's 2003, "From RTM-notation to ENP-score-notation"
 531 http://jim2003.agglo-montbeliard.fr/articles/laurson.pdf
 532 ::
 533
 534 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.
 535
 536 If the divisions in the rtm-list are events, the event durations are interpreted as relative durations, and a list of events is returned.
 537 code::
 538 // using numbers as score
 539 [3, [1, 2, 1], 1].convertRhythm; // List[ 0.75, 1.5, 0.75 ]
 540 [2, [1, 3, [1, [2, 1, 1, 1]], 1, 3], 1].convertRhythm;
 541 [2, [1, [1, [2, 1, 1, 1]]], 1].convertRhythm;
 542 [2, [1, [1, [2, 1, 1, 1]]], 2].convertRhythm; // repeat
 543 [2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm; // negative value is tied over.
 544
 545 // sound example
 546 Pbind(\degree, Pseries(0, 1, inf), \dur, Pseq([2, [1, [1, [2, 1, 1, -1]]], 2].convertRhythm)).play;
 547 ::
 548