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