HelpSource/Classes/Array.schelp

   1 class:: Array
   2 summary:: fixed size collection
   3 related:: Reference/Literals, Classes/List
   4 categories:: Collections>Ordered
   5
   6 description::
   7 Arrays are ArrayedCollections whose slots may contain any object. Arrays have a fixed maximum size beyond which they cannot grow. For expandable arrays, use the link::Classes/List:: class.
   8
   9 strong::Literal Arrays:: can be created at compile time, and are very efficient. See link::Reference/Literals:: for information.
  10
  11 For handling strong::multidimensional arrays::, there are specific methods which are covered in the helpfile link::Guides/J-concepts-in-SC::.
  12
  13 note::
  14 For Arrays, the code::add:: method may or may not return the same Array object. It will add the argument to the receiver if there is space, otherwise it returns a new Array object with the argument added. Thus the proper usage of code::add:: with an Array is to always assign the result as follows:
  15 code::
  16     z = z.add(obj);
  17 ::
  18 This allows an efficient use of resources, only growing the array when it needs to. The link::Classes/List:: class manages the Array internally, and in many cases is more suitable.
  19 ::
  20
  21 Elements can be put into an existing slot with code::a.put(2,obj):: and accessed with
  22 code::a.at(2):: or code::a[2]::
  23
  24 See link::Classes/ArrayedCollection:: for the principal methods: at, put, clipAt, wrapAt, etc...
  25
  26
  27 ClassMethods::
  28
  29 method::new
  30 Create a new array with size 0 that can grow up to the fixed size.
  31 argument::maxSize
  32 The maximum size of the array.
  33
  34 method::newClear
  35 Create a new array with all slots filled with nils.
  36 argument::indexedSize
  37 The size of the array.
  38
  39 method::with
  40 Create a new Array whose slots are filled with the given arguments.
  41 This is the same as the method in ArrayedCollection, but is reimplemented here to be more efficient.
  42 code::
  43 Array.with(7, 'eight',  9).postln;
  44 ::
  45
  46 copymethod:: Collection *fill
  47
  48 copymethod:: Collection *fill2D
  49
  50 copymethod:: Collection *fillND
  51
  52 copymethod:: Collection *newFrom
  53
  54 copymethod:: ArrayedCollection *geom
  55
  56 copymethod:: ArrayedCollection *series
  57
  58 copymethod:: ArrayedCollection *iota
  59
  60 copymethod:: Collection *interpolation
  61
  62 copymethod:: Collection *rand
  63
  64 copymethod:: Collection *rand2
  65
  66 copymethod:: Collection *linrand
  67
  68 copymethod:: Collection *exprand
  69
  70 copymethod:: Collection *fib
  71
  72
  73
  74
  75
  76 InstanceMethods::
  77
  78 copymethod:: ArrayedCollection -at
  79
  80 copymethod:: ArrayedCollection -put
  81
  82 copymethod:: ArrayedCollection -insert
  83
  84 copymethod:: ArrayedCollection -overWrite
  85
  86 copymethod:: ArrayedCollection -clipAt
  87
  88 copymethod:: ArrayedCollection -wrapAt
  89
  90 copymethod:: ArrayedCollection -foldAt
  91
  92 copymethod:: ArrayedCollection -slice
  93
  94 copymethod:: ArrayedCollection -clipPut
  95
  96 copymethod:: ArrayedCollection -wrapPut
  97
  98 copymethod:: ArrayedCollection -foldPut
  99
 100 copymethod:: ArrayedCollection -swap
 101
 102 copymethod:: ArrayedCollection -replace
 103
 104 copymethod:: ArrayedCollection -++
 105
 106 copymethod:: ArrayedCollection -add
 107
 108 copymethod:: ArrayedCollection -addAll
 109
 110 copymethod:: ArrayedCollection -addFirst
 111
 112 copymethod:: ArrayedCollection -removeAt
 113
 114 copymethod:: ArrayedCollection -collect
 115
 116 copymethod:: ArrayedCollection -do
 117
 118 copymethod:: ArrayedCollection -reverseDo
 119
 120 copymethod:: ArrayedCollection -deepCollect
 121
 122 copymethod:: ArrayedCollection -reshape
 123
 124 copymethod:: ArrayedCollection -bubble
 125
 126 copymethod:: ArrayedCollection -unbubble
 127
 128 copymethod:: ArrayedCollection -windex
 129
 130 copymethod:: ArrayedCollection -size
 131
 132 copymethod:: ArrayedCollection -normalize
 133
 134 copymethod:: ArrayedCollection -normalizeSum
 135
 136 copymethod:: ArrayedCollection -plot
 137
 138 method::reverse
 139 Returns a new Array whose elements are reversed. The receiver is unchanged.
 140 code::
 141 x = [1, 2, 3];
 142 z = x.reverse;
 143 x.postln;
 144 z.postln;
 145 ::
 146
 147 method::scramble
 148 Returns a new Array whose elements have been scrambled. The receiver is unchanged.
 149 code::
 150 [1, 2, 3, 4, 5, 6].scramble.postln;
 151 ::
 152
 153 method::mirror
 154 Return a new Array which is the receiver made into a palindrome.
 155 The receiver is unchanged.
 156 code::
 157 [1, 2, 3, 4].mirror.postln;
 158 ::
 159
 160 method::mirror1
 161 Return a new Array which is the receiver made into a palindrome with the last element removed.
 162 This is useful if the list will be repeated cyclically, the first element will not get played twice.
 163 The receiver is unchanged.
 164 code::
 165 [1, 2, 3, 4].mirror1.postln;
 166 ::
 167
 168 method::mirror2
 169 Return a new Array which is the receiver concatenated with a reversal of itself.
 170 The center element is duplicated. The receiver is unchanged.
 171 code::
 172 [1, 2, 3, 4].mirror2.postln;
 173 ::
 174
 175 method::stutter
 176 Return a new Array whose elements are repeated n times. The receiver is unchanged.
 177 code::
 178 [1, 2, 3].stutter(2).postln;
 179 ::
 180 argument::n
 181 Number of repeats.
 182
 183 method::rotate
 184 Return a new Array whose elements are in rotated order. The receiver is unchanged.
 185 code::
 186 [1, 2, 3, 4, 5].rotate(1).postln;
 187 [1, 2, 3, 4, 5].rotate(-1).postln;
 188 [1, 2, 3, 4, 5].rotate(3).postln;
 189 ::
 190 argument::n
 191 Number of elements to rotate. Negative n values rotate left, postive n values
 192 rotate right.
 193
 194 method::pyramid
 195 Return a new Array whose elements have been reordered via one of 10 "counting" algorithms.
 196 Run the examples to see the algorithms.
 197 code::
 198 10.do({ arg i;
 199         [1, 2, 3, 4].pyramid(i + 1).postcs;
 200 });
 201 ::
 202 argument::patternType
 203 Choose counting algorithm. The algorithms are numbered 1 through 10.
 204
 205 method::pyramidg
 206 Like pyramid, but keep the resulting values grouped in subarrays.
 207 code::
 208 // compare:
 209 [1, 2, 3, 4].pyramid(1).postln;
 210 [1, 2, 3, 4].pyramidg(1).postln;
 211 ::
 212
 213 method::sputter
 214 Return a new Array of length maxlen with the items partly repeated (random choice of given probability).
 215 code::
 216 // compare:
 217 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].sputter(0.5, 16).postln;
 218 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].sputter(0.8, 8).postln;
 219 ::
 220 argument::probability
 221 Probability of repeat.
 222 argument::maxlen
 223 The length of the new Array.
 224
 225 method::lace
 226 Returns a new Array whose elements are interlaced sequences of the elements of the receiver's subcollections, up to size length. The receiver is unchanged.
 227 code::
 228 x = [ [1, 2, 3], 6, List["foo", 'bar']];
 229 y = x.lace(12);
 230 x.postln;
 231 y.postln;
 232 ::
 233
 234 method::permute
 235 Returns a new Array whose elements are the nthPermutation of the elements of the receiver. The receiver is unchanged.
 236 code::
 237 x = [ 1, 2, 3];
 238 6.do({|i| x.permute(i).postln;});
 239 ::
 240
 241 method::allTuples
 242 Returns a new Array whose elements contain all possible combinations of the receiver's subcollections.
 243 code::
 244 [[1, 2, 3, 4, 5], [10, 20, 30]].allTuples;
 245 [[1, 2, 3, 4, 5], [10, 20, 30], [5, 6]].allTuples;
 246 ::
 247
 248 method::wrapExtend
 249 Returns a new Array whose elements are repeated sequences of the receiver, up to size length. The receiver is unchanged.
 250 code::
 251 x = [ 1, 2, 3, "foo", 'bar' ];
 252 y = x.wrapExtend(9);
 253 x.postln;
 254 y.postln;
 255 ::
 256
 257 method::foldExtend
 258 Same as wrapExtend but the sequences fold back on the list elements.
 259 code::
 260 x = [ 1, 2, "foo"];
 261 y = x.foldExtend(9);
 262 x.postln;
 263 y.postln;
 264 ::
 265
 266 method::clipExtend
 267 Same as wrapExtend but the sequences "clip" (return their last element) rather than wrapping.
 268 code::
 269 x = [ 1, 2, "foo"];
 270 y = x.clipExtend(9);
 271 x.postln;
 272 y.postln;
 273 ::
 274
 275 method::slide
 276 Return a new Array whose elements are repeated subsequences from the receiver.
 277 Easier to demonstrate than explain.
 278 code::
 279 [1, 2, 3, 4, 5, 6].slide(3, 1).postcs;
 280 [1, 2, 3, 4, 5, 6].slide(3, 2).postcs;
 281 [1, 2, 3, 4, 5, 6].slide(4, 1).postcs;
 282 ::
 283
 284 method::shift
 285 Shift the values of the array n steps to the right (n positive) or to the left(n negative),
 286 dropping the excess and filling empty space with zero.
 287 code::
 288 [1, 2, 3, 4, 5, 6].shift(3).postln;
 289 [1, 2, 3, 4, 5, 6].shift(-3).postln;
 290 ::
 291
 292 method::containsSeqColl
 293 Returns true if the receiver Array contains any instance of SequenceableCollection
 294 code::
 295 [1, 2, 3, 4].containsSeqColl.postln
 296 [1, 2, [3], 4].containsSeqColl.postln
 297 ::
 298
 299 method::powerset
 300 Returns all possible combinations of the array's elements.
 301 code::
 302 [1, 2, 3].powerset.postln
 303 [1, 2, 3].powerset.sort({ |a, b| a.size > b.size }); // sort by size, big first
 304 [1, 2, 3].powerset.sort({ |a, b| a.size > b.size }).reverse; // by size, small first
 305 ::
 306 powerset is also supported in Collection:
 307 code::
 308 Set[1, 2, 3].powerset;
 309 List[1, 2, 3].powerset
 310 (a: 1, b: 2, c: 3).powerset;
 311 ::
 312
 313 method::envirPairs
 314 Given an array of symbols, this returns an array of pairs of (symbol, value) from the current environment.
 315 This can then be used as arguments for a Synth, or in an OSC message.
 316 code::
 317 e = (freq: 340, amp: 0.001, strangeness: 0.85);
 318 e.use {
 319         [\amp, \taste, \strangeness].envirPairs;
 320 }
 321 ::
 322
 323 method::flop
 324 Invert rows and colums in a two dimensional Array (turn inside out).
 325 See also: Function, SequenceableCollection.
 326 code::
 327 [[1, 2, 3], [4, 5, 6]].flop;
 328 [[1, 2, 3], [4, 5, 6], [7, 8]].flop; // shorter array wraps
 329 [].flop; // result is always 2-d.
 330 ::
 331
 332 method::multiChannelExpand
 333 Used by UGens to perform multi channel expansion. Same as flop.
 334
 335 method::source
 336 Some UGens return Arrays of OutputProxy when instantiated. This method allows you to
 337 get at the source UGen.
 338 code::
 339 z = Pan2.ar;
 340 z.postln;
 341 z.source.postln;
 342 ::
 343
 344 method::fork
 345 Used within Routines and assumes an array of functions, from which subroutines are created. The subroutines are played while the outer Routine carries on. The join parameter expresses after how many subroutines complete the outer Routine is allowed to go on. By default this happens after all subroutines have completed.
 346 code::
 347 // an array of routine functions:
 348 (
 349 a = [
 350         { 1.wait; \done_one.postln },
 351         { 0.5.wait; \done_two.postln },
 352         { 0.2.wait; \done_three.postln }
 353 ];
 354 )
 355 // join after 0
 356 (
 357 Routine {
 358         "join = 0.".postcln;
 359         a.fork(0); \doneAll.postln;
 360 }.play;
 361 )
 362 // join after 1
 363 (
 364 Routine {
 365         "join = 1.".postcln;
 366         a.fork(1); \doneAll.postln;
 367 }.play;
 368 )
 369 // join after all
 370 (
 371 Routine {
 372         "join = a.size (default).".postcln;
 373         a.fork; \doneAll.postln;
 374 }.play;
 375 )
 376
 377 poll(trig, label, trigid)
 378 apply an array of Poll units to an array of UGens (see those helpfiles for more details).
 379
 380 s.boot;
 381 (
 382 x = {
 383         SinOsc.ar([0.1, 0.2], 0).poll * 0.1
 384 }.play;
 385 )
 386 x.trace; // By tracing the Synth you can see the two Poll units we created
 387 x.free
 388 ::
 389
 390 method::dpoll
 391 apply an array of Dpoll units to an array of UGens (see those helpfiles for more details).
 392
 393 method::atIdentityHash
 394 This method is used by IdentitySet to search for a key among its members.
 395
 396 method::atIdentityHashInPairs
 397 This method is used by IdentityDictionary to search for a key among its members.
 398
 399 method::asString
 400 Returns a string representing the Array. May not be compileable due to ellision (...) of excessive arguments.
 401
 402 method::asCompileString
 403 Returns a string that will compile to return an Array equal to the receiver.
 404
 405 method::isValidUGenInput
 406 Returns true. Arrays are valid UGen inputs.
 407
 408 method::asRawOSC
 409 Returns the OSC measse as an Int8Array. Receiver must be a bundle.
 410 code::
 411 [0.1, [\s_new, \default, -1, 1, 1, \freq, 1961]].asRawOSC;
 412 ::
 413