404 lines
8.9 KiB
Racket
404 lines
8.9 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label racket))
|
|
|
|
@title{List}
|
|
list of items of variable size@section{related}
|
|
Classes/Array
|
|
@section{categories}
|
|
Collections>Ordered
|
|
|
|
@section{description}
|
|
|
|
List is a subclass of SequenceableCollection with unlimited growth in size. Although not a subclass of link::Classes/Array:: or its superclass link::Classes/ArrayedCollection:: it uses an Array in its implementation and is in many cases interchangeable with one. (List implements many of the same methods as Array.)
|
|
|
|
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 link::Classes/Array:: helpfile.) List has no size limitation and is thus more flexible, but has slightly more overhead.
|
|
|
|
@racketblock[
|
|
(
|
|
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 link::Classes/SequenceableCollection:: or link::Classes/Collection:: and are documented in those helpfiles.
|
|
|
|
]
|
|
@section{CLASSMETHODS}
|
|
|
|
|
|
@section{method}
|
|
new
|
|
Creates a List with the initial capacity given by strong::size::.
|
|
|
|
@section{method}
|
|
newClear
|
|
Creates a List with the initial capacity given by strong::size:: and slots filled with nil.
|
|
|
|
@section{method}
|
|
copyInstance
|
|
Creates a List by copying strong::a@section{List}
|
|
's array variable.
|
|
|
|
@section{method}
|
|
newUsing
|
|
Creates a List using strong::anArray::.
|
|
|
|
@section{INSTANCEMETHODS}
|
|
|
|
|
|
@section{method}
|
|
asArray
|
|
Returns a new link::Classes/Array:: based upon this List.
|
|
|
|
@section{method}
|
|
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.
|
|
|
|
@racketblock[
|
|
(
|
|
x = List[1, 2, 3];
|
|
x.array.add("foo");
|
|
x.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
array
|
|
Sets the List's Array.
|
|
|
|
@section{method}
|
|
at
|
|
Return the item at strong::index::.
|
|
|
|
@racketblock[
|
|
List[ 1, 2, 3 ].at(0).postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
clipAt
|
|
Same as link::#-at::, but values for strong::index:: greater than the size of the List will be clipped to the last index.
|
|
|
|
@racketblock[
|
|
y = List[ 1, 2, 3 ];
|
|
y.clipAt(13).postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
wrapAt
|
|
Same as link::#-at::, but values for strong::index:: greater than the size of the List will be wrapped around to 0.
|
|
|
|
@racketblock[
|
|
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
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
foldAt
|
|
Same as link::#-at::, but values for strong::index:: greater than the size of the List will be folded back.
|
|
|
|
@racketblock[
|
|
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
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
put
|
|
Put strong::item:: at strong::index::, replacing what is there.
|
|
|
|
@section{method}
|
|
clipPut
|
|
Same as link::#-put::, but values for strong::index:: greater than the size of the List will be clipped to the last index.
|
|
|
|
@section{method}
|
|
wrapPut
|
|
Same as link::#-put::, but values for strong::index:: greater than the size of the List will be wrapped around to 0.
|
|
|
|
@section{method}
|
|
foldPut
|
|
Same as link::#-put::, but values for strong::index:: greater than the size of the List will be folded back.
|
|
|
|
@section{method}
|
|
add
|
|
Adds an strong::item:: to the end of the List.
|
|
|
|
@section{method}
|
|
addFirst
|
|
Inserts the strong::item:: at the beginning of the List.
|
|
|
|
@section{method}
|
|
insert
|
|
Inserts the strong::item:: into the contents of the List at the indicated strong::index::.
|
|
|
|
@section{method}
|
|
pop
|
|
Remove and return the last element of the List.
|
|
|
|
@section{method}
|
|
grow
|
|
Increase the size of the List by strong::sizeIncrease:: number of slots.
|
|
|
|
@section{method}
|
|
removeAt
|
|
Remove and return the element at strong::index::, shrinking the size of the List.
|
|
|
|
@racketblock[
|
|
y = List[ 1, 2, 3 ];
|
|
y.removeAt(1);
|
|
y.postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
fill
|
|
Inserts the item into the contents of the receiver, possibly returning a new collection. @section{note}
|
|
the difference between this and link::Classes/Collection#fill#Collection's *fill::.::
|
|
|
|
@racketblock[
|
|
(
|
|
var z;
|
|
z = List[1, 2, 3, 4];
|
|
z.fill(4).postln;
|
|
z.fill([1,2,3,4]).postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
do
|
|
Iterate over the elements in order, calling the function for each element. The function is passed two arguments, the element and an index.
|
|
|
|
@racketblock[
|
|
List['a', 'b', 'c'].do({ arg item, i; [i, item].postln; });
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
reverseDo
|
|
Iterate over the elements in reverse order, calling the function for each element. The function is passed two arguments, the element and an index.
|
|
|
|
@racketblock[
|
|
List['a', 'b', 'c'].reverseDo({ arg item, i; [i, item].postln; });
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
pairsDo
|
|
Calls function for each subsequent pair of elements in the List. The function is passed the two elements and an index.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4, 5, 6].pairsDo({ arg a, b; [a, b].postln; });
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
copyRange
|
|
Return a new List which is a copy of the indexed slots of the receiver from start to end.
|
|
|
|
@racketblock[
|
|
(
|
|
var y, z;
|
|
z = List[1, 2, 3, 4, 5];
|
|
y = z.copyRange(1,3);
|
|
z.postln;
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
copySeries
|
|
Return a new List consisting of the values starting at strong::first::, then every step of the distance between strong::first:: and strong::second::, up until strong::last::.
|
|
|
|
@racketblock[
|
|
(
|
|
var y, z;
|
|
z = List[1, 2, 3, 4, 5, 6];
|
|
y = z.copySeries(0, 2, 5);
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
putSeries
|
|
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::.
|
|
|
|
@racketblock[
|
|
(
|
|
var y, z;
|
|
z = List[1, 2, 3, 4, 5, 6];
|
|
y = z.putSeries(0, 2, 5, "foo");
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
reverse
|
|
Return a new List whose elements are reversed.
|
|
|
|
@racketblock[
|
|
(
|
|
var y, z;
|
|
z = List[1, 2, 3, 4];
|
|
y = z.reverse;
|
|
z.postln;
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
scramble
|
|
Returns a new List whose elements have been scrambled. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4, 5, 6].scramble.postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
mirror
|
|
Return a new List which is the receiver made into a palindrome. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4].mirror.postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
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.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4].mirror1.postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
mirror2
|
|
Return a new List which is the receiver concatenated with a reversal of itself. The center element is duplicated. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4].mirror2.postln;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
stutter
|
|
Return a new List whose elements are repeated strong::n:: times. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3].stutter(2).postln;
|
|
::
|
|
|
|
rotate
|
|
Return a new List whose elements are in rotated order. Negative strong::n:: values rotate left, positive strong::n:: values rotate right. The receiver is unchanged.
|
|
]
|
|
|
|
@racketblock[
|
|
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;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
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.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4].pyramid(1).postln;
|
|
|
|
(
|
|
10.do({ arg i;
|
|
List[1, 2, 3, 4].pyramid(i + 1).postcs;
|
|
});
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
lace
|
|
Returns a new List whose elements are interlaced sequences of the elements of the receiver's subcollections, up to size strong::length::. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
(
|
|
x = List[ [1, 2, 3], 6, List["foo", 'bar']];
|
|
y = x.lace(12);
|
|
x.postln;
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
permute
|
|
Returns a new List whose elements are the strong::nthPermutation:: of the elements of the receiver. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
(
|
|
x = List[ 1, 2, 3];
|
|
6.do({|i| x.permute(i).postln;});
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
wrapExtend
|
|
Returns a new List whose elements are repeated sequences of the receiver, up to size strong::length::. The receiver is unchanged.
|
|
|
|
@racketblock[
|
|
(
|
|
x = List[ 1, 2, 3, "foo", 'bar' ];
|
|
y = x.wrapExtend(9);
|
|
x.postln;
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
foldExtend
|
|
Same as link::#-wrapExtend:: but the sequences fold back on the list elements.
|
|
|
|
@racketblock[
|
|
(
|
|
x = List[ 1, 2, "foo"];
|
|
y = x.foldExtend(9);
|
|
x.postln;
|
|
y.postln;
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
slide
|
|
Return a new List whose elements are repeated subsequences from the receiver. Easier to demonstrate than explain.
|
|
|
|
@racketblock[
|
|
List[1, 2, 3, 4, 5, 6].slide(3, 1).postcs;
|
|
List[1, 2, 3, 4, 5, 6].slide(3, 2).postcs;
|
|
List[1, 2, 3, 4, 5, 6].slide(4, 1).postcs;
|
|
::
|
|
|
|
]
|
|
@section{method}
|
|
dump
|
|
Dump the List's Array.
|
|
|
|
@section{method}
|
|
clear
|
|
Replace the List's Array with a new empty one.
|
|
|
|
|