What is the difference exactly between .cap() and .size() ?
Don't know. I just needed array size, and started using size() :-).
Working from memory;
In previous versions of ChucK .cap() could be used to get the length of the array, it could also (undocumentedly) be used to (re)set the length though at the expense of re-initialising all elements.
In 1.2.1.2 .size() was added which can be used exactly like .cap() to get the size of the array. It is overloaded to set the size, which should not re-initialise the existing elements (this works as far as I'm aware) and which should initialise any new ones added (this does not always happen in practice). In the meantime .cap() is no longer overloaded to set array length.
Why this is like it is I don't know, in theory it might have broken some code, like how we could set all array elements of a array of type int to 0 while maintaining the same length using this;
foo.cap( foo.cap() );
more generally; using that we could re-initialise all elements without being aware of the type of the array. In practice I never heard about this resulting in any complaints.