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