HelpSource/Classes/List.schelp

   1 CLASS::List
   2 summary::list of items of variable size
   3 related::Classes/Array
   4 categories::Collections>Ordered
   5
   6 DESCRIPTION::
   7 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.)
   8
   9 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.
  10 code::
  11 (
  12 x = Array.new(3);
  13 y = List.new(3);
  14 5.do({ arg i; z = x.add(i); y.add(i); });
  15 x.postln; z.postln; y.postln;
  16 )
  17 ::
  18
  19 Many of List's methods are inherited from link::Classes/SequenceableCollection:: or link::Classes/Collection:: and are documented in those helpfiles.
  20
  21 CLASSMETHODS::
  22
  23 method::new
  24 Creates a List with the initial capacity given by strong::size::.
  25
  26 method::newClear
  27 Creates a List with the initial capacity given by strong::size:: and slots filled with nil.
  28
  29 method::copyInstance
  30 Creates a List by copying strong::aList::'s array variable.
  31
  32 method::newUsing
  33 Creates a List using strong::anArray::.
  34
  35 INSTANCEMETHODS::
  36
  37 method::asArray
  38 Returns a new link::Classes/Array:: based upon this List.
  39
  40 method::array
  41 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.
  42 code::
  43 (
  44 x = List[1, 2, 3];
  45 x.array.add("foo");
  46 x.postln;
  47 )
  48 ::
  49
  50 method::array
  51 Sets the List's Array.
  52
  53 method::at
  54 Return the item at strong::index::.
  55 code::
  56 List[ 1, 2, 3 ].at(0).postln;
  57 ::
  58
  59 method::clipAt
  60 Same as link::#-at::, but values for strong::index:: greater than the size of the List will be clipped to the last index.
  61 code::
  62 y = List[ 1, 2, 3 ];
  63 y.clipAt(13).postln;
  64 ::
  65
  66 method::wrapAt
  67 Same as link::#-at::, but values for strong::index:: greater than the size of the List will be wrapped around to 0.
  68 code::
  69 y = List[ 1, 2, 3 ];
  70 y.wrapAt(3).postln; // this returns the value at index 0
  71 y.wrapAt(4).postln; // this returns the value at index 1
  72 ::
  73
  74 method::foldAt
  75 Same as link::#-at::, but values for strong::index:: greater than the size of the List will be folded back.
  76 code::
  77 y = List[ 1, 2, 3 ];
  78 y.foldAt(3).postln; // this returns the value at index 1
  79 y.foldAt(4).postln; // this returns the value at index 0
  80 y.foldAt(5).postln; // this returns the value at index 1
  81 ::
  82
  83 method::put
  84 Put strong::item:: at strong::index::, replacing what is there.
  85
  86 method::clipPut
  87 Same as link::#-put::, but values for strong::index:: greater than the size of the List will be clipped to the last index.
  88
  89 method::wrapPut
  90 Same as link::#-put::, but values for strong::index:: greater than the size of the List will be wrapped around to 0.
  91
  92 method::foldPut
  93 Same as link::#-put::, but values for strong::index:: greater than the size of the List will be folded back.
  94
  95 method::add
  96 Adds an strong::item:: to the end of the List.
  97
  98 method::addFirst
  99 Inserts the strong::item:: at the beginning of the List.
 100
 101 method::insert
 102 Inserts the strong::item:: into the contents of the List at the indicated strong::index::.
 103
 104 method::pop
 105 Remove and return the last element of the List.
 106
 107 method::grow
 108 Increase the size of the List by strong::sizeIncrease:: number of slots.
 109
 110 method::removeAt
 111 Remove and return the element at strong::index::, shrinking the size of the List.
 112 code::
 113 y = List[ 1, 2, 3 ];
 114 y.removeAt(1);
 115 y.postln;
 116 ::
 117
 118 method::fill
 119 Inserts the item into the contents of the receiver, possibly returning a new collection. note::the difference between this and link::Classes/Collection#fill#Collection's *fill::.::
 120 code::
 121 (
 122 var z;
 123 z = List[1, 2, 3, 4];
 124 z.fill(4).postln;
 125 z.fill([1,2,3,4]).postln;
 126 )
 127 ::
 128
 129 method::do
 130 Iterate over the elements in order, calling the function for each element. The function is passed two arguments, the element and an index.
 131 code::
 132 List['a', 'b', 'c'].do({ arg item, i; [i, item].postln; });
 133 ::
 134
 135 method::reverseDo
 136 Iterate over the elements in reverse order, calling the function for each element. The function is passed two arguments, the element and an index.
 137 code::
 138 List['a', 'b', 'c'].reverseDo({ arg item, i; [i, item].postln; });
 139 ::
 140
 141 method::pairsDo
 142 Calls function for each subsequent pair of elements in the List. The function is passed the two elements and an index.
 143 code::
 144 List[1, 2, 3, 4, 5, 6].pairsDo({ arg a, b; [a, b].postln; });
 145 ::
 146
 147 method::copyRange
 148 Return a new List which is a copy of the indexed slots of the receiver from start to end.
 149 code::
 150 (
 151 var y, z;
 152 z = List[1, 2, 3, 4, 5];
 153 y = z.copyRange(1,3);
 154 z.postln;
 155 y.postln;
 156 )
 157 ::
 158
 159 method::copySeries
 160 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::.
 161 code::
 162 (
 163 var y, z;
 164 z = List[1, 2, 3, 4, 5, 6];
 165 y = z.copySeries(0, 2, 5);
 166 y.postln;
 167 )
 168 ::
 169
 170 method::putSeries
 171 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::.
 172 code::
 173 (
 174 var y, z;
 175 z = List[1, 2, 3, 4, 5, 6];
 176 y = z.putSeries(0, 2, 5, "foo");
 177 y.postln;
 178 )
 179 ::
 180
 181 method::reverse
 182 Return a new List whose elements are reversed.
 183 code::
 184 (
 185 var y, z;
 186 z = List[1, 2, 3, 4];
 187 y = z.reverse;
 188 z.postln;
 189 y.postln;
 190 )
 191 ::
 192
 193 method::scramble
 194 Returns a new List whose elements have been scrambled. The receiver is unchanged.
 195 code::
 196 List[1, 2, 3, 4, 5, 6].scramble.postln;
 197 ::
 198
 199 method::mirror
 200 Return a new List which is the receiver made into a palindrome. The receiver is unchanged.
 201 code::
 202 List[1, 2, 3, 4].mirror.postln;
 203 ::
 204
 205 method::mirror1
 206 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.
 207 code::
 208 List[1, 2, 3, 4].mirror1.postln;
 209 ::
 210
 211 method::mirror2
 212 Return a new List which is the receiver concatenated with a reversal of itself. The center element is duplicated. The receiver is unchanged.
 213 code::
 214 List[1, 2, 3, 4].mirror2.postln;
 215 ::
 216
 217 method::stutter
 218 Return a new List whose elements are repeated strong::n:: times. The receiver is unchanged.
 219 code::
 220 List[1, 2, 3].stutter(2).postln;
 221 ::
 222
 223 rotate
 224 Return a new List whose elements are in rotated order. Negative strong::n:: values rotate left, postive strong::n:: values rotate right. The receiver is unchanged.
 225 code::
 226 List[1, 2, 3, 4, 5].rotate(1).postln;
 227 List[1, 2, 3, 4, 5].rotate(-1).postln;
 228 List[1, 2, 3, 4, 5].rotate(3).postln;
 229 ::
 230
 231 method::pyramid
 232 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.
 233 code::
 234 List[1, 2, 3, 4].pyramid(1).postln;
 235
 236 (
 237 10.do({ arg i;
 238         List[1, 2, 3, 4].pyramid(i + 1).postcs;
 239 });
 240 )
 241 ::
 242
 243 method::lace
 244 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.
 245 code::
 246 (
 247 x = List[ [1, 2, 3], 6, List["foo", 'bar']];
 248 y = x.lace(12);
 249 x.postln;
 250 y.postln;
 251 )
 252 ::
 253
 254 method::permute
 255 Returns a new List whose elements are the strong::nthPermutation:: of the elements of the receiver. The receiver is unchanged.
 256 code::
 257 (
 258 x = List[ 1, 2, 3];
 259 6.do({|i| x.permute(i).postln;});
 260 )
 261 ::
 262
 263 method::wrapExtend
 264 Returns a new List whose elements are repeated sequences of the receiver, up to size strong::length::. The receiver is unchanged.
 265 code::
 266 (
 267 x = List[ 1, 2, 3, "foo", 'bar' ];
 268 y = x.wrapExtend(9);
 269 x.postln;
 270 y.postln;
 271 )
 272 ::
 273
 274 method::foldExtend
 275 Same as link::#-lace:: but the sequences fold back on the list elements.
 276 code::
 277 (
 278 x = List[ 1, 2, "foo"];
 279 y = x.foldExtend(9);
 280 x.postln;
 281 y.postln;
 282 )
 283 ::
 284
 285 method::slide
 286 Return a new List whose elements are repeated subsequences from the receiver. Easier to demonstrate than explain.
 287 code::
 288 List[1, 2, 3, 4, 5, 6].slide(3, 1).postcs;
 289 List[1, 2, 3, 4, 5, 6].slide(3, 2).postcs;
 290 List[1, 2, 3, 4, 5, 6].slide(4, 1).postcs;
 291 ::
 292
 293 method::dump
 294 Dump the List's Array.
 295
 296 method::clear
 297 Replace the List's Array with a new empty one.