List

Superclass: SequenceableCollection

List is a subclass of SequenceableCollection with unlimited growth in size. Although not a subclass of Array or its superclass ArrayedCollection it uses an Array in its implementation and is in many cases interchangeable with one. (List implements many of the same methods.)

Arrays have a fixed maximum size. If you add beyond that size a new Array is created and returned, but you must use an assignment statement or the new array will be lost. (See the Array helpfile.) List has no size limitation and is thus more flexible, but has slightly more overhead.

(

x = Array.new(3);

y = List.new(3);

5.do({arg i; z = x.add(i); y.add(i);});

x.postln; z.postln; y.postln;

)

Many of List's methods are inherited from SequenceableCollection or Collection and are documented in those helpfiles.

Creation

*new(size)

Creates a List with the initial capacity given by size.

*newClear(size)

Creates a List with the initial capacity given by size and slots filled with nil.

*copyInstance(aList)

Creates a List by copying aList's array variable.

*newUsing(anArray)

Creates a List using anArray.

Instance Methods

asArray

Returns a new Array based upon this List.

array

Returns the List's Array, allowing it to be manipulated directly. This should only be necessary for exotic manipulations not implemented in List or its superclasses.

(

x = List[1, 2, 3];

x.array.add("foo");

x.postln;

)

array_(anArray)

Sets the List's Array.

at(index)

Return the item at index.

List[ 1, 2, 3 ].at(0).postln;

clipAt(index)

Same as at, but values for index greater than the size of the List will be clipped to the last index.

y = List[ 1, 2, 3 ];

y.clipAt(13).postln;

wrapAt(index)

Same as at, but values for index greater than the size of the List will be wrapped around to 0.

y = List[ 1, 2, 3 ];

y.wrapAt(3).postln; // this returns the value at index 0

y.wrapAt(4).postln; // this returns the value at index 1

foldAt(index)

Same as at, but values for index greater than the size of the List will be folded back.

y = List[ 1, 2, 3 ];

y.foldAt(3).postln; // this returns the value at index 1

y.foldAt(4).postln; // this returns the value at index 0

y.foldAt(5).postln; // this returns the value at index 1

put(index, item)

Put item at index, replacing what is there.

clipPut(index, item)

Same as put, but values for index greater than the size of the List will be clipped to the last index.

wrapPut(index, item)

Same as put, but values for index greater than the size of the List will be wrapped around to 0.

foldPut(index)

Same as put, but values for index greater than the size of the List will be folded back.

add(item)

Adds an item to the end of the List.

addFirst(item)

Inserts the item at the beginning of the List.

insert(index, item)

Inserts the item into the contents of the List at the indicated index.

pop

Remove and return the last element of the List.

grow(sizeIncrease)

Increase the size of the List by sizeIncrease number of slots.

removeAt(index)

Remove and return the element at index, shrinking the size of the List.

y = List[ 1, 2, 3 ];

y.removeAt(1);

y.postln;

fill(value)

Inserts the item into the contents of the receiver, possibly returning a new collection. Note the difference between this and Collection's *fill.

(

var z;

z = List[1, 2, 3, 4];

z.fill(4).postln;

z.fill([1,2,3,4]).postln;

)

do(function)

Iterate over the elements in order, calling the function for each element. The function is passed two arguments, the element and an index.

List['a', 'b', 'c'].do({ arg item, i; [i, item].postln; });

reverseDo(function)

Iterate over the elements in reverse order, calling the function for each element. The function is passed two arguments, the element and an index.

List['a', 'b', 'c'].reverseDo({ arg item, i; [i, item].postln; });

copyRange(start, end)

Return a new List which is a copy of the indexed slots of the receiver from start to end.

(

var y, z;

z = List[1, 2, 3, 4, 5];

y = z.copyRange(1,3);

z.postln;

y.postln;

)

copySeries(first, second, last)

Return a new List consisting of the values starting at first, then every step of the distance between first and second, up until last.

(

var y, z;

z = List[1, 2, 3, 4, 5, 6];

y = z.copySeries(0, 2, 5);

y.postln;

)

putSeries(first, second, last, value)

Put value at every index starting at first, then every step of the distance between first and second, up until last.

(

var y, z;

z = List[1, 2, 3, 4, 5, 6];

y = z.putSeries(0, 2, 5, "foo");

y.postln;

)

reverse

Return a new List whose elements are reversed.

(

var y, z;

z = List[1, 2, 3, 4];

y = z.reverse;

z.postln;

y.postln;

)

scramble

Returns a new List whose elements have been scrambled. The receiver is unchanged.

List[1, 2, 3, 4, 5, 6].scramble.postln;

mirror

Return a new List which is the receiver made into a palindrome.

The receiver is unchanged.

List[1, 2, 3, 4].mirror.postln;

mirror1

Return a new List which is the receiver made into a palindrome with the last element removed.

This is useful if the list will be repeated cyclically, the first element will not get played twice.

The receiver is unchanged.

List[1, 2, 3, 4].mirror1.postln;

mirror2

Return a new List which is the receiver concatenated with a reversal of itself. The center element is duplicated. The receiver is unchanged.

List[1, 2, 3, 4].mirror2.postln;

stutter(n)

Return a new List whose elements are repeated n times. The receiver is unchanged.

List[1, 2, 3].stutter(2).postln;

rotate(n)

Return a new List whose elements are in rotated order. Negative n values rotate left, postive n values rotate right. The receiver is unchanged.

List[1, 2, 3, 4, 5].rotate(1).postln;

List[1, 2, 3, 4, 5].rotate(-1).postln;

List[1, 2, 3, 4, 5].rotate(3).postln;

pyramid

Return a new List whose elements have been reordered via one of 10 "counting" algorithms.

The algorithms are numbered 1 through 10. Run the examples to see the algorithms.

List[1, 2, 3, 4].pyramid(1).postln;

(

10.do({ arg i;

List[1, 2, 3, 4].pyramid(i + 1).asCompileString.postln;

});

)

lace(length)

Returns a new List whose elements are interlaced sequences of the elements of the receiver's subcollections, up to size length. The receiver is unchanged.

(

x = List[ [1, 2, 3], 6, List["foo", 'bar']];

y = x.lace(12);

x.postln;

y.postln;

)

permute(nthPermutation)

Returns a new List whose elements are the nthPermutation of the elements of the receiver. The receiver is unchanged.

(

x = List[ 1, 2, 3];

6.do({|i| x.permute(i).postln;});

)

wrapExtend(length)

Returns a new List whose elements are repeated sequences of the receiver, up to size length. The receiver is unchanged.

(

x = List[ 1, 2, 3, "foo", 'bar' ];

y = x.wrapExtend(9);

x.postln;

y.postln;

)

foldExtend(length)

Same as lace but the sequences fold back on the list elements.

(

x = List[ 1, 2, "foo"];

y = x.foldExtend(9);

x.postln;

y.postln;

)

slide(windowLength, stepSize)

Return a new List whose elements are repeated subsequences from the receiver.

Easier to demonstrate than explain.

List[1, 2, 3, 4, 5, 6].slide(3, 1).asCompileString.postln;

List[1, 2, 3, 4, 5, 6].slide(3, 2).asCompileString.postln;

List[1, 2, 3, 4, 5, 6].slide(4, 1).asCompileString.postln;

dump

Dump the List's Array.

clear

Replace the List's Array with a new empty one.