HelpSource/Classes/ArrayedCollection.schelp

   1 CLASS::ArrayedCollection
   2 categories::Collections>Ordered
   3 summary:: Abstract superclass of Collections of fixed maximum size
   4
   5 DESCRIPTION::
   6 ArrayedCollection is an abstract class, a subclass of SequenceableCollections whose elements are held in a vector of slots. Instances of ArrayedCollection have a fixed maximum size beyond which they may not grow.
   7
   8 Its principal subclasses are link::Classes/Array:: (for holding objects), and link::Classes/RawArray::, from which link::Classes/Int8Array::, link::Classes/FloatArray::, link::Classes/Signal:: etc. inherit.
   9
  10 CLASSMETHODS::
  11
  12 method::newClear
  13 Creates a new instance with strong::indexedSize:: indexable slots. The slots are filled with link::Classes/Nil::, zero or something else appropriate to the type of indexable slots in the object.
  14 code::
  15 Array.newClear(4).postln;
  16 ::
  17
  18 method::with
  19 Create a new ArrayedCollection whose slots are filled with the given arguments.
  20 code::
  21 Array.with(7, 'eight',  9).postln;
  22 ::
  23
  24 method::series
  25 Fill an ArrayedCollection with an arithmetic series.
  26 code::
  27 Array.series(5, 10, 2).postln;
  28 ::
  29
  30 method::geom
  31 Fill an ArrayedCollection with a geometric series.
  32 code::
  33 Array.geom(5, 1, 3).postln;
  34 ::
  35
  36 method::iota
  37 Fills an ArrayedCollection with a counter. See link::Guides/J-concepts-in-SC:: for more examples.
  38 code::
  39 Array.iota(2, 3);
  40 Array.iota(2, 3, 4);
  41 ::
  42
  43 method::fill2D
  44 Creates a 2 dimensional ArrayedCollection of the given sizes. The items are determined by evaluation of the supplied function. The function is passed row and column indexes as arguments. See link::Guides/J-concepts-in-SC::
  45 code::
  46 Array.fill2D(2, 4, 0);
  47 Array.fill2D(3, 4, { arg r, c; r*c+c; });
  48 ::
  49
  50 method::fill3D
  51 Creates a 3 dimensional ArrayedCollection of the given sizes. The items are determined by evaluation of the supplied function. The function is passed plane, row and column indexes as arguments. See link::Guides/J-concepts-in-SC::
  52 code::
  53 Array.fill3D(2, 3, 4, { arg p, r, c; p; });
  54 ::
  55
  56 method::fillND
  57 Creates a N dimensional ArrayedCollection where N is the size of the array strong::dimensions::. The items are determined by evaluation of the supplied function. The function is passed N number of indexes as arguments.
  58 code::
  59 Array.fillND([4, 4], { arg a, b; a+b; });                       //2d
  60 Array.fillND([4, 4, 4], { arg a, b, c; a+b*c; });               //3d
  61 Array.fillND([1, 2, 3, 4], { arg a, b, c, d; b+d; });           //4d
  62 ::
  63
  64 INSTANCEMETHODS::
  65
  66 method::size
  67 Return the number of elements the ArrayedCollection.
  68
  69 method::maxSize
  70 Return the maximum number of elements the ArrayedCollection can hold. For example, link::Classes/Array::s may initialise themselves with a larger capacity than the number of elements added.
  71 code::
  72 [4, 5, 6].maxSize; // gosh
  73 ::
  74
  75 method::at
  76 Return the item at strong::index::.
  77
  78 method::clipAt
  79 Same as link::#-at::, but values for strong::index:: greater than the size of the ArrayedCollection will be clipped to the last index.
  80 code::
  81 y = [ 1, 2, 3 ];
  82 y.clipAt(13).postln;
  83 ::
  84
  85 method::wrapAt
  86 Same as link::#-at::, but values for strong::index:: greater than the size of the ArrayedCollection will be wrapped around to 0.
  87 code::
  88 y = [ 1, 2, 3 ];
  89 y.wrapAt(3).postln; // this returns the value at index 0
  90 y.wrapAt(4).postln; // this returns the value at index 1
  91 ::
  92
  93 method::foldAt
  94 Same as link::#-at::, but values for strong::index:: greater than the size of the ArrayedCollection will be folded back.
  95 code::
  96 y = [ 1, 2, 3 ];
  97 y.foldAt(3).postln; // this returns the value at index 1
  98 y.foldAt(4).postln; // this returns the value at index 0
  99 y.foldAt(5).postln; // this returns the value at index 1
 100 ::
 101
 102 method::plot
 103 Plot data in a GUI window. See link::Reference/plot:: for more details.
 104
 105 method::swap
 106 Swap the values at indices i and j.
 107 code::
 108 [ 1, 2, 3 ].swap(0, 2).postln;
 109 ::
 110
 111 method::put
 112 Put strong::item:: at strong::index::, replacing what is there.
 113
 114 method::clipPut
 115 Same as link::#-put::, but values for strong::index:: greater than the size of the ArrayedCollection will be clipped to the last index.
 116
 117 method::wrapPut
 118 Same as link::#-put::, but values for strong::index:: greater than the size of the ArrayedCollection will be wrapped around to 0.
 119
 120 method::foldPut
 121 Same as link::#-put::, but values for strong::index:: greater than the size of the ArrayedCollection will be folded back.
 122
 123 method::putEach
 124 Put the strong::values:: in the corresponding indices given by strong::keys::. If one of the two argument arrays is longer then it will wrap.
 125 code::
 126 y = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 127 y.putEach([4, 7], [\smelly, \head]);
 128 y.putEach([2, 3, 5, 6], \wotsits);
 129 ::
 130
 131 method::indexOf
 132 Return the first index containing an item which matches strong::item::.
 133 code::
 134 y = [ \the, \symbol, \collection, \contains, \my, \symbol ];
 135 y.indexOf(\symbol);
 136 ::
 137
 138 method::includes
 139 Return a boolean indicating whether the collection contains anything matching strong::item::.
 140 code::
 141 y = [ \the, \symbol, \collection, \contains, \my, \symbol ];
 142 y.includes(\symbol);
 143 y.includes(\solipsism);
 144 ::
 145
 146 method::indexOfGreaterThan
 147 Return the first index containing an item which is greater than strong::item::.
 148 code::
 149 y = [ 10, 5, 77, 55, 12, 123];
 150 y.indexOfGreaterThan(70);
 151 ::
 152
 153 method::removeAt
 154 Remove and return the element at strong::index::, shrinking the size of the ArrayedCollection.
 155 code::
 156 y = [ 1, 2, 3 ];
 157 y.removeAt(1);
 158 y.postln;
 159 ::
 160
 161 method::takeAt
 162 Similar to link::#-removeAt::, but does not maintain the order of the items following the one that was removed. Instead, the last item is placed into the position of the removed item and the array's size decreases by one.
 163 code::
 164 y = [ 1, 2, 3, 4, 5 ];
 165 y.takeAt(1);
 166 y.postln;
 167 ::
 168
 169 method::takeThese
 170 Removes all items in the receiver for which the strong::func:: answers true. The function is passed two arguments, the item and an integer index. note::that order is not preserved. See link::#-takeAt::.
 171 code::
 172 y = [ 1, 2, 3, 4 ];
 173 y.takeThese({ arg item, index; item.odd; });    //remove odd items
 174 y.postln;
 175 ::
 176
 177 method::add
 178 Adds an item to an ArrayedCollection if there is space. If there is not any space left in the object then this method returns a new ArrayedCollection. For this reason, you should always assign the result of add to a variable - never depend on add changing the receiver.
 179 code::
 180 (
 181 // z and y are the same object
 182 var y, z;
 183 z = [1, 2, 3];
 184 y = z.add(4);
 185 z.postln;
 186 y.postln;
 187 )
 188
 189 (
 190 // in this case a new object is returned
 191 var y, z;
 192 z = [1, 2, 3, 4];
 193 y = z.add(5);
 194 z.postln;
 195 y.postln;
 196 )
 197 ::
 198
 199 method::addAll
 200 Adds all the elements of aCollection to the contents of the receiver, possibly returning a new collection.
 201 code::
 202 (
 203 // in this case a new object is returned
 204 var y, z;
 205 z = [1, 2, 3, 4];
 206 y = z.addAll([7, 8, 9]);
 207 z.postln;
 208 y.postln;
 209 )
 210 ::
 211
 212 method::extend
 213 Extends the receiver to match strong::size:: by adding a number of strong::item::s. If strong::size:: is less than receiver size then truncate.
 214 code::
 215 (
 216 var y, z;
 217 z = [1, 2, 3, 4];
 218 y = z.extend(10, 9);            //fill up with 9 until the size equals 10
 219 z.postln;
 220 y.postln;
 221 )
 222 ::
 223
 224 method::fill
 225 Inserts the item into the contents of the receiver, possibly returning a new collection. note::the difference between this and link::Classes/Collection#fill#Collection's *fill::.::
 226 code::
 227 (
 228 var z;
 229 z = [1, 2, 3, 4];
 230 z.fill(4).postln;
 231 z.fill([1,2,3,4]).postln;
 232 )
 233 ::
 234
 235 method::insert
 236 Inserts the item into the contents of the receiver, possibly returning a new collection.
 237 code::
 238 (
 239 // in this case a new object is returned
 240 var y, z;
 241 z = [1, 2, 3, 4];
 242 y = z.insert(1, 999);
 243 z.postln;
 244 y.postln;
 245 )
 246 ::
 247
 248 method::addFirst
 249 Inserts the item before the contents of the receiver, possibly returning a new collection.
 250 code::
 251 (
 252 // in this case a new object is returned
 253 var y, z;
 254 z = [1, 2, 3, 4];
 255 y = z.addFirst(999);
 256 z.postln;
 257 y.postln;
 258 )
 259 ::
 260
 261 method::pop
 262 Remove and return the last element of the ArrayedCollection.
 263 code::
 264 (
 265 var z;
 266 z = [1, 2, 3, 4];
 267 z.pop.postln;
 268 z.postln;
 269 )
 270 ::
 271
 272 method::grow
 273 Increase the size of the ArrayedCollection by strong::sizeIncrease:: number of slots,  possibly returning a new collection.
 274
 275 method::growClear
 276 Increase the size of the ArrayedCollection by strong::sizeIncrease:: number of slots,  returning a new collection with link::Classes/Nil::s in the added slots.
 277 code::
 278 // Compare:
 279 [4,5,6].grow(5);
 280 [4,5,6].growClear(5);
 281 ::
 282
 283 method::copyRange
 284 Return a new ArrayedCollection which is a copy of the indexed slots of the receiver from strong::start:: to strong::end::.
 285 code::x.copyRange(a, b):: can also be written as code::x[a..b]::
 286 code::
 287 (
 288 var y, z;
 289 z = [1, 2, 3, 4, 5];
 290 y = z.copyRange(1,3);
 291 z.postln;
 292 y.postln;
 293 )
 294 ::
 295
 296 method::copySeries
 297 Return a new ArrayedCollection consisting of the values starting at strong::first::, then every step of the distance between strong::first:: and strong::second::, up until strong::last::.
 298 code::x.copySeries(a, b, c):: can also be written as code::x[a, b..c]::
 299 code::
 300 (
 301 var y, z;
 302 z = [1, 2, 3, 4, 5, 6];
 303 y = z.copySeries(0, 2, 5);
 304 y.postln;
 305 )
 306 ::
 307
 308 method::seriesFill
 309 Fill the receiver with an arithmetic progression. The first element will be strong::start::, the second strong::start + step::, the third strong::start + step + step:: ...
 310 code::
 311 (
 312 var y;
 313 y = Array.newClear(15);
 314 y.seriesFill(5, 3);
 315 y.postln;
 316 )
 317 ::
 318
 319 method::putSeries
 320 Put strong::value:: at every index starting at strong::first::, then every step of the distance between strong::first:: and strong::second::, up until strong::last::.
 321 code::x.putSeries(a, b, c, val):: can also be written as code::x[a, b..c] = val::
 322 code::
 323 (
 324 var y, z;
 325 z = [1, 2, 3, 4, 5, 6];
 326 y = z.putSeries(0, 2, 5, "foo");
 327 y.postln;
 328 )
 329 ::
 330
 331 method::++
 332 Concatenate the contents of the two collections into a new ArrayedCollection.
 333 code::
 334 (
 335 var y, z;
 336 z = [1, 2, 3, 4];
 337 y = z ++ [7, 8, 9];
 338 z.postln;
 339 y.postln;
 340 )
 341 ::
 342
 343 method::reverse
 344 Return a new ArrayedCollection whose elements are reversed.
 345 code::
 346 (
 347 var y, z;
 348 z = [1, 2, 3, 4];
 349 y = z.reverse;
 350 z.postln;
 351 y.postln;
 352 )
 353 ::
 354
 355 method::do
 356 Iterate over the elements in order, calling the function for each element. The function is passed two arguments, the element and an index.
 357 code::
 358 ['a', 'b', 'c'].do({ arg item, i; [i, item].postln; });
 359 ::
 360
 361 method::reverseDo
 362 Iterate over the elements in reverse order, calling the function for each element. The function is passed two arguments, the element and an index.
 363 code::
 364 ['a', 'b', 'c'].reverseDo({ arg item, i; [i, item].postln; });
 365 ::
 366
 367 method::collect
 368 Answer a new collection which consists of the results of function evaluated for each item in the collection. The function is passed two arguments, the item and an integer index. See link::Classes/Collection:: helpfile for examples.
 369
 370 method::deepCollect
 371 The same as link::#-collect::, but can look inside sub-arrays up to the specified strong::depth::.
 372 code::
 373 a = [99, [4,6,5], [[32]]];
 374 a.deepCollect(1, {|item| item.isArray}).postln;
 375 a.deepCollect(2, {|item| item.isArray}).postln;
 376 a.deepCollect(3, {|item| item.isArray}).postln;
 377 ::
 378
 379 method::windex
 380 Interprets the array as a list of probabilities which should sum to 1.0 and returns a random index value based on those probabilities.
 381 code::
 382 (
 383 Array.fill(10, {
 384         [0.1, 0.6, 0.3].windex;
 385 }).postln;
 386 )
 387 ::
 388
 389 method::normalizeSum
 390 Returns the Array resulting from :
 391 code::
 392 (this / this.sum)
 393 ::
 394 so that the array will sum to 1.0.
 395
 396 This is useful for using with windex or wchoose.
 397 code::
 398 [1, 2, 3].normalizeSum.postln;
 399 ::
 400
 401 method::normalize
 402 Returns a new Array with the receiver items normalized between strong::min:: and strong::max::.
 403 code::
 404 [1, 2, 3].normalize;                    //default min=0, max= 1
 405 [1, 2, 3].normalize(-20, 10);
 406 ::
 407
 408 method::perfectShuffle
 409 Returns a copy of the receiver with its items split into two equal halves, then reconstructed by interleaving the two halves. note::use an even number of item pairs in order to not loose any items in the shuffle.::
 410 code::
 411 (
 412 var y, z;
 413 z = [ 1, 2, 3, 4, 5, 6 ];
 414 y = z.perfectShuffle;
 415 z.postln;
 416 y.postln;
 417 )
 418 ::
 419
 420 method::performInPlace
 421 Performs a method in place, within a certain region [from..to], returning the same array.
 422 code::
 423 a = (0..10);
 424 a.performInPlace(\normalizeSum, 3, 6);
 425 ::
 426
 427 method::rank
 428 Rank is the number of dimensions in a multidimensional array.
 429 code::
 430 a = [4,7,6,8];
 431 a.rank;
 432 a = [[4,7],[6,8]];
 433 a.rank;
 434 ::
 435
 436 method::shape
 437 For a multidimensional array, returns the number of elements along each dimension.
 438 code::
 439 a = [4,7,6,8];
 440 a.shape;
 441 a = [[4,7],[6,8]];
 442 a.shape;
 443 ::
 444
 445 method::reshape
 446 For a multidimensional array, rearranges the data using the desired number of elements along each dimension. The data may be extended using wrapExtend if needed.
 447 code::
 448 a = [4,7,6,8];
 449 a.reshape(2,2);
 450 a.reshape(2,3);
 451 ::
 452
 453 method::find
 454 Finds the starting index of a number of elements contained in the array.
 455 code::
 456 a = (0..10);
 457 a.find([4, 5, 6]);
 458 ::
 459
 460 method::replace
 461 Return a new array in which a number of elements have been replaced by another.
 462 code::
 463 a = (0..10) ++ (0..10);
 464 a.replace([4, 5, 6], 100);
 465 a.replace([4, 5, 6], [1734, 1985, 1860]);
 466 ::
 467 this method is inherited by link::Classes/String:: :
 468 code::
 469 a = "hello world";
 470 a.replace("world", "word");
 471 ::
 472
 473 method::asRandomTable
 474 Return an integral table that can be used to generate random numbers with a specified distribution.
 475 (see link::Guides/Randomness:: helpfile for a more detailed example)
 476 code::
 477 (
 478 a = (0..100) ++ (100..50) / 100; // distribution
 479 a = a.asRandomTable;
 480 )
 481 ::
 482
 483 method::tableRand
 484 Returns a new random number from a random table.
 485 code::
 486 (
 487 a = (0..100) ++ (100..50) / 100; // distribution
 488 a = a.asRandomTable;
 489 20.do { a.tableRand.postln };
 490 )
 491 ::
 492
 493 method::msgSize
 494 Return the size of an osc message in bytes
 495 code::
 496 a = ["/s_new", "default", -1, "freq", 440];
 497 a.msgSize;
 498 ::
 499
 500 method::bundleSize
 501 Return the size of an osc bundle in bytes
 502 code::
 503 a = [["/s_new", "default", -1, "freq", 440], ["/s_new", "default", -1, "freq", 220]];
 504 a.bundleSize;
 505 ::
 506
 507 method::asciiPlot
 508 For an ArrayedCollection containing numbers (e.g. audio data) this renders a plot in the post window using asterisks and spaces (works best if you use a monospace font in your post window).
 509 code::
 510 a = (0, pi/10 .. 5pi).collect{|val| val.sin};
 511 a.asciiPlot;
 512 ::