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 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:
  10 code::
  11     z = z.add(obj);
  12 ::
  13 This allows an efficient use of resources, only growing the array when it needs to. The List class manages the Array for you, and in many cases is more suitable.
  14
  15 Elements can be put into an existing slot with code::a.put(2,obj):: and accessed with
  16 code::a.at(2):: or code::a[2]::
  17
  18 See link::Classes/ArrayedCollection:: for the principal methods: at, put, clipAt, wrapAt, etc...
  19
  20 Literal Arrays can be created at compile time, and are very efficient. See link::Reference/Literals:: for information.
  21
  22 ClassMethods::
  23
  24 method::new
  25 Create a new array with size 0 that can grow up to the fixed size.
  26 argument::maxSize
  27 The maximum size of the array.
  28
  29 method::newClear
  30 Create a new array with all slots filled with nils.
  31 argument::indexedSize
  32 The size of the array.
  33
  34 method::with
  35 Create a new Array whose slots are filled with the given arguments.
  36 This is the same as the method in ArrayedCollection, but is reimplemented here to be more efficient.
  37 code::
  38 Array.with(7, 'eight',  9).postln;
  39 ::
  40
  41 InstanceMethods::
  42
  43 method::reverse
  44 Returns a new Array whose elements are reversed. The receiver is unchanged.
  45 code::
  46 x = [1, 2, 3];
  47 z = x.reverse;
  48 x.postln;
  49 z.postln;
  50 ::
  51
  52 method::scramble
  53 Returns a new Array whose elements have been scrambled. The receiver is unchanged.
  54 code::
  55 [1, 2, 3, 4, 5, 6].scramble.postln;
  56 ::
  57
  58 method::mirror
  59 Return a new Array which is the receiver made into a palindrome.
  60 The receiver is unchanged.
  61 code::
  62 [1, 2, 3, 4].mirror.postln;
  63 ::
  64
  65 method::mirror1
  66 Return a new Array which is the receiver made into a palindrome with the last element removed.
  67 This is useful if the list will be repeated cyclically, the first element will not get played twice.
  68 The receiver is unchanged.
  69 code::
  70 [1, 2, 3, 4].mirror1.postln;
  71 ::
  72
  73 method::mirror2
  74 Return a new Array which is the receiver concatenated with a reversal of itself.
  75 The center element is duplicated. The receiver is unchanged.
  76 code::
  77 [1, 2, 3, 4].mirror2.postln;
  78 ::
  79
  80 method::stutter
  81 Return a new Array whose elements are repeated n times. The receiver is unchanged.
  82 code::
  83 [1, 2, 3].stutter(2).postln;
  84 ::
  85 argument::n
  86 Number of repeats.
  87
  88 method::rotate
  89 Return a new Array whose elements are in rotated order. The receiver is unchanged.
  90 code::
  91 [1, 2, 3, 4, 5].rotate(1).postln;
  92 [1, 2, 3, 4, 5].rotate(-1).postln;
  93 [1, 2, 3, 4, 5].rotate(3).postln;
  94 ::
  95 argument::n
  96 Number of elements to rotate. Negative n values rotate left, postive n values
  97 rotate right.
  98
  99 method::pyramid
 100 Return a new Array whose elements have been reordered via one of 10 "counting" algorithms.
 101 Run the examples to see the algorithms.
 102 code::
 103 10.do({ arg i;
 104         [1, 2, 3, 4].pyramid(i + 1).postcs;
 105 });
 106 ::
 107 argument::n
 108 Choose counting algorithm. The algorithms are numbered 1 through 10.
 109
 110 method::pyramidg
 111 Like pyramid, but keep the resulting values grouped in subarrays.
 112 code::
 113 // compare:
 114 [1, 2, 3, 4].pyramid(1).postln;
 115 [1, 2, 3, 4].pyramidg(1).postln;
 116 ::
 117
 118 method::sputter
 119 Return a new Array of length maxlen with the items partly repeated (random choice of given probability).
 120 code::
 121 // compare:
 122 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].sputter(0.5, 16).postln;
 123 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].sputter(0.8, 8).postln;
 124 ::
 125 argument::probability
 126 Probability of repeat.
 127 argument::maxlen
 128 The length of the new Array.
 129
 130 method::lace
 131 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.
 132 code::
 133 x = [ [1, 2, 3], 6, List["foo", 'bar']];
 134 y = x.lace(12);
 135 x.postln;
 136 y.postln;
 137 ::
 138
 139 method::permute
 140 Returns a new Array whose elements are the nthPermutation of the elements of the receiver. The receiver is unchanged.
 141 code::
 142 x = [ 1, 2, 3];
 143 6.do({|i| x.permute(i).postln;});
 144 ::
 145
 146 method::allTuples
 147 Returns a new Array whose elements contain all possible combinations of the receiver's subcollections.
 148 code::
 149 [[1, 2, 3, 4, 5], [10, 20, 30]].allTuples;
 150 [[1, 2, 3, 4, 5], [10, 20, 30], [5, 6]].allTuples;
 151 ::
 152
 153 method::wrapExtend
 154 Returns a new Array whose elements are repeated sequences of the receiver, up to size length. The receiver is unchanged.
 155 code::
 156 x = [ 1, 2, 3, "foo", 'bar' ];
 157 y = x.wrapExtend(9);
 158 x.postln;
 159 y.postln;
 160 ::
 161
 162 method::foldExtend
 163 Same as wrapExtend but the sequences fold back on the list elements.
 164 code::
 165 x = [ 1, 2, "foo"];
 166 y = x.foldExtend(9);
 167 x.postln;
 168 y.postln;
 169 ::
 170
 171 method::clipExtend
 172 Same as wrapExtend but the sequences "clip" (return their last element) rather than wrapping.
 173 code::
 174 x = [ 1, 2, "foo"];
 175 y = x.clipExtend(9);
 176 x.postln;
 177 y.postln;
 178 ::
 179
 180 method::slide
 181 Return a new Array whose elements are repeated subsequences from the receiver.
 182 Easier to demonstrate than explain.
 183 code::
 184 [1, 2, 3, 4, 5, 6].slide(3, 1).postcs;
 185 [1, 2, 3, 4, 5, 6].slide(3, 2).postcs;
 186 [1, 2, 3, 4, 5, 6].slide(4, 1).postcs;
 187 ::
 188
 189 method::shift
 190 Shift the values of the array n steps to the right (n positive) or to the left(n negative),
 191 dropping the excess and filling empty space with zero.
 192 code::
 193 [1, 2, 3, 4, 5, 6].shift(3).postln;
 194 [1, 2, 3, 4, 5, 6].shift(-3).postln;
 195 ::
 196
 197 method::containsSeqColl
 198 Returns true if the receiver Array contains any instance of SequenceableCollection
 199 code::
 200 [1, 2, 3, 4].containsSeqColl.postln
 201 [1, 2, [3], 4].containsSeqColl.postln
 202 ::
 203
 204 method::powerset
 205 Returns all possible combinations of the array's elements.
 206 code::
 207 [1, 2, 3].powerset.postln
 208 [1, 2, 3].powerset.sort({ |a, b| a.size > b.size }); // sort by size, big first
 209 [1, 2, 3].powerset.sort({ |a, b| a.size > b.size }).reverse; // by size, small first
 210 ::
 211 powerset is also supported in Collection:
 212 code::
 213 Set[1, 2, 3].powerset;
 214 List[1, 2, 3].powerset
 215 (a: 1, b: 2, c: 3).powerset;
 216 ::
 217
 218 method::envirPairs
 219 Given an array of symbols, this returns an array of pairs of (symbol, value) from the current environment.
 220 This can then be used as arguments for a Synth, or in an OSC message.
 221 code::
 222 e = (freq: 340, amp: 0.001, strangeness: 0.85);
 223 e.use {
 224         [\amp, \taste, \strangeness].envirPairs;
 225 }
 226 ::
 227
 228 method::flop
 229 Invert rows and colums in a two dimensional Array (turn inside out).
 230 See also: Function, SequenceableCollection.
 231 code::
 232 [[1, 2, 3], [4, 5, 6]].flop;
 233 [[1, 2, 3], [4, 5, 6], [7, 8]].flop; // shorter array wraps
 234 [].flop; // result is always 2-d.
 235 ::
 236
 237 method::multiChannelExpand
 238 Used by UGens to perform multi channel expansion. Same as flop.
 239
 240 method::source
 241 Some UGens return Arrays of OutputProxy when instantiated. This method allows you to
 242 get at the source UGen.
 243 code::
 244 z = Pan2.ar;
 245 z.postln;
 246 z.source.postln;
 247 ::
 248
 249 method::fork
 250 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.
 251 code::
 252 // an array of routine functions:
 253 (
 254 a = [
 255         { 1.wait; \done_one.postln },
 256         { 0.5.wait; \done_two.postln },
 257         { 0.2.wait; \done_three.postln }
 258 ];
 259 )
 260 // join after 0
 261 (
 262 Routine {
 263         "join = 0.".postcln;
 264         a.fork(0); \doneAll.postln;
 265 }.play;
 266 )
 267 // join after 1
 268 (
 269 Routine {
 270         "join = 1.".postcln;
 271         a.fork(1); \doneAll.postln;
 272 }.play;
 273 )
 274 // join after all
 275 (
 276 Routine {
 277         "join = a.size (default).".postcln;
 278         a.fork; \doneAll.postln;
 279 }.play;
 280 )
 281
 282 poll(trig, label, trigid)
 283 apply an array of Poll units to an array of UGens (see those helpfiles for more details).
 284
 285 s.boot;
 286 (
 287 x = {
 288         SinOsc.ar([0.1, 0.2], 0).poll * 0.1
 289 }.play;
 290 )
 291 x.trace; // By tracing the Synth you can see the two Poll units we created
 292 x.free
 293 ::
 294
 295 method::dpoll
 296 apply an array of Dpoll units to an array of UGens (see those helpfiles for more details).
 297
 298 method::atIdentityHash
 299 This method is used by IdentitySet to search for a key among its members.
 300
 301 method::atIdentityHashInPairs
 302 This method is used by IdentityDictionary to search for a key among its members.
 303
 304 method::asString
 305 Returns a string representing the Array. May not be compileable due to ellision (...) of excessive arguments.
 306
 307 method::asCompileString
 308 Returns a string that will compile to return an Array equal to the receiver.
 309
 310 method::isValidUGenInput
 311 Returns true. Arrays are valid UGen inputs.
 312
 313 method::asRawOSC
 314 Returns the OSC measse as an Int8Array. Receiver must be a bundle.
 315 code::
 316 [0.1, [\s_new, \default, -1, 1, 1, \freq, 1961]].asRawOSC;
 317 ::
 318