/* Arrays (which we have briefly seen) are one of the most basic ways to store and access data in almost any programming language. SuperCollider has some VERY powerful Array based manipulations, and learning how to use them for data storage can make you code compact, and easier to debug. First, let's look at how Arrays can be created. One way is to just place values between square brackets. For the purpose of these examples, we'll use a global variable 'a' for our Arrays and show how the data can be accessed and operated on. */

a = [0, 2, 4, 5, 6, 9, 11, 12];

// accessing data: use the 'at' method. You can choose values from 0 to the size of the array - 1:

a.at(0);

a.at(1);

a[4];

// with bracket notation, you can also ask for a range of elements

a[3..6];

// not with 'at'

a.at(3..6);

// return the first element

a.first;

// or the last element

a.last;

// returns the size of the array

a.size;

// one thing we have already seen is the use of the 'do' 

// method on an array to iterate through its values:

a.do({arg thisData, inc;

"thisData's current value is: ".post;

thisData.postln;

"inc's current value is: ".post;

inc.postln;

});

// you can also do many mathmatical operations on an array. 

// These usually return a new Array, and leave the original untouched

a + 60;

a; // stil the original data

// if you want you can also replace the original array with the new data

a = a + 60; // now, 'a' will be the new values

a.sqrt; // take the square root of all the values in an Array

// why is this still equal to [60, 62 ... etc ]?

a;

a.sum; // what do all the elements in the array add up to?

// returns an array where the elements are all scaled so the sum of the 

// ENTIRE Array is '1'

a.normalizeSum; 

a.normalizeSum.sum;

// you can't add new values to an array. 

// BUT - there is an 'add' method that will return

// a new Array with the value added in.

a.add(800);

// untouched!

a;

b = a.add(800);

b;

b = a.addFirst(800);

b;

b = a.insert(4, 800);

b;

// so, like the example above where we reassign a new Array to the same 

// variable, you do see this quite often

a;

a = a.add(800);

a;

a = a.add(32767);

a;

// you can reverse the elements of an Array, but once again, 

// this actually returns a new Array

a.reverse;

a;

// while this kind of 'protection' of the data may seem a little strange, 

// it is actually one of the things that make arrays powerful. With one set 

// of data, you can create a number of permutations from that data, and not 

// actually worry about altering the original state of the data.

a;

a.reverse;

a.scramble;

a.mirror; // don't repeat the 'last' value

a.mirror1; // don't repeat the 'first' value or the 'last' value

a.mirror2; // repeat the first and last values

a.stutter(3); // repeat every element 'n' times

a.rotate(3); // bring the last three elements to the front

a.rotate(-5); // first five go to the end

// returns an array of 'n' elements, where the new elements are 

// repeats of the original values wrapped

a.wrapExtend(40); 

a.foldExtend(40); // same, but folds

a.clipExtend(40); // stick on the last value

// take the first three elements, then the three elements starting with 

// element 1, etc

a.slide(3, 1); 

a.slide(3, 2); // change the 'stepSize' parameter

//a.slide(3, 0); // this would be VERY bad... inf loop

// every possible combination of the elements!!!

b = a.powerset;

b.size;

b.at(100);

// notice that, with all of that, 'a' is still just 'a'

a;

// Arrays can hold just about any object:

a = [PC(\c, 4), PC(\d, 4), PC(\ef, 4), PC(\f, 4), PC(\g, 4), PC(\a, 4), PC(\b, 4), PC(\c, 5)];

// however, you may not be able to do things to the Array itself:

a.freq; // doesn't understand

// BUT - you can ask the Array to perform an operation on the 

// Objects in the Array the message you want to send does not have 

// a '.', but is in single quotes

a.performUnaryOp(\freq); 

// 'a' still hasn't changed though!

a;

b = a.performUnaryOp(\freq);

// back to something more readable:

a = [0, 2, 4, 5, 6, 9, 11, 12];

a.mirror;

a.mirror1;

a.mirror2;

// See the Array helpfile for more examples