HelpSource/Classes/Collection.schelp

   1 CLASS::Collection
   2 summary::Abstract superclass of all collections
   3 related::Classes/List, Classes/Array, Classes/Dictionary, Classes/Bag, Classes/Set, Classes/SortedList
   4 categories::Collections
   5
   6 DESCRIPTION::
   7 Collection is an abstract class. You do not create direct instances of Collection.
   8 There are many types of Collections including link::Classes/List::, link::Classes/Array::, link::Classes/Dictionary::, link::Classes/Bag::, link::Classes/Set::, link::Classes/SortedList::, etc. See link::Overviews/Collections:: for a complete class tree.
   9
  10 CLASSMETHODS::
  11
  12 method::newFrom
  13 Creates a new Collection from another collection. This supports the interface for the method "as".
  14 code::
  15 Array.newFrom(Set[4, 2, 1]);
  16 Set.newFrom(Array[4, 2, 1]);
  17 [1, 2, 3, 4, 3, 2].as(Set); // as(someClass) calls someClass.newFrom(this)
  18 ::
  19
  20 method::with
  21 Creates a new Collection from the args.
  22 code::
  23 Array.with(4, 2, 1);
  24 ::
  25
  26 method::fill
  27 Creates a Collection of the given size, the elements of which are determined by evaluation the given function. The function is passed the index as an argument.
  28 code::
  29 Array.fill(4, { arg i; i * 2 });
  30 ::
  31
  32 INSTANCEMETHODS::
  33
  34 subsection::Accessing
  35
  36 method::size
  37 Answers the number of objects contained in the Collection.
  38 code::
  39 List[1, 2, 3, 4].size;
  40 ::
  41
  42 method::isEmpty
  43 Answer whether the receiver contains no objects.
  44 code::
  45 List[].isEmpty;
  46 ::
  47
  48 subsection::Adding and Removing
  49
  50 method::add
  51 Add anObject to the receiver.
  52 code::
  53 List[1, 2].add(3);
  54 ::
  55
  56 method::addAll
  57 Add all items in aCollection to the receiver.
  58 code::
  59 List[1, 2].addAll(List[3, 4]);
  60 ::
  61
  62 method::remove
  63 Remove anObject from the receiver. Answers the removed object.
  64 code::
  65 (
  66 var a;
  67 a = List[1, 2, 3, 4];
  68 a.remove(3);
  69 a;
  70 )
  71 ::
  72
  73 method::removeAll
  74 Remove all items in aCollection from the receiver.
  75 code::
  76 List[1, 2, 3, 4].removeAll(List[2, 3]);
  77 ::
  78 note::that multiple items in the receiver will not necessarily be removed
  79 code::
  80 ~closet = [\hat, \hat, \hat, \coat, \coat, \shoe, \shoe];
  81 ~closet.removeAll([\hat, \coat, \shoe, \shoe]); // Doesn't empty the closet, just removes what we wanted to
  82 ::
  83 See link::#-removeEvery:: for a related method that removes all occurrences.
  84 ::
  85
  86 method::removeEvery
  87 Remove all occurrences of the items in aCollection from the receiver.
  88 code::
  89 List[1, 2, 3, 2, 3, 2, 3, 4].removeEvery(List[2, 3]);
  90 ::
  91
  92 method::removeAllSuchThat
  93 Remove all items in the receiver for which function answers link::Classes/True::. The function is passed two arguments, the item and an integer index. Answers the objects which have been removed.
  94 code::
  95 (
  96 var a;
  97 a = List[1, 2, 3, 4];
  98 a.removeAllSuchThat({ arg item, i; item < 3 });
  99 a;
 100 )
 101 ::
 102
 103 method::putEach
 104 Put the values in the corresponding indices given by keys. If one of the two argument arrays is longer then it will wrap.
 105 code::
 106 y = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 107 y.putEach([4, 7], [\smelly, \head]);
 108 y.putEach([2, 3, 5, 6], \wotsits);
 109 ::
 110
 111 method::atAll
 112 Return a collection of all the items for the keys.
 113 code::
 114 y = [\a, \b, \c];
 115 y.atAll([0, 2]);
 116 ::
 117
 118 subsection::Testing
 119
 120 method::includes
 121 Answer whether anObject is contained in the receiver.
 122 code::
 123 List[1, 2, 3, 4].includes(3);
 124 ::
 125
 126 method::includesAny
 127 Answer whether any item in aCollection is contained in the receiver.
 128 code::
 129 List[1, 2, 3, 4].includesAny(List[4, 5]);
 130 ::
 131
 132 method::includesAll
 133 Answer whether all items in aCollection are contained in the receiver.
 134 code::
 135 List[1, 2, 3, 4].includesAll(List[4, 5]);
 136 ::
 137
 138 method::matchItem
 139 Returns link::Classes/True:: if this includes the strong::item::.
 140
 141 subsection::Iteration
 142
 143 method::do
 144 Evaluates strong::function:: for each item in the collection. The function is passed two arguments, the item and an integer index.
 145 code::
 146 List[1, 2, 3, 4].do({ arg item, i; item.postln });
 147 ::
 148
 149 method::collect
 150 Answer a new collection which consists of the results of strong::function:: evaluated for each item in the collection. The function is passed two arguments, the item and an integer index.
 151 code::
 152 List[1, 2, 3, 4].collect({ arg item, i; item + 10 });
 153 ::
 154 If you want to control what type of collection is returned, use link::#-collectAs::(function, class).
 155
 156 method::select
 157 Answer a new collection which consists of all items in the receiver for which strong::function:: answers link::Classes/True::. The function is passed two arguments, the item and an integer index.
 158 code::
 159 List[1, 2, 3, 4].select({ arg item, i; item.even });
 160 ::
 161 If you want to control what type of collection is returned, use link::#-selectAs::(function, class).
 162
 163 method::reject
 164 Answer a new collection which consists of all items in the receiver for which strong::function:: answers link::Classes/False::. The function is passed two arguments, the item and an integer index.
 165 code::
 166 List[1, 2, 3, 4].reject({ arg item, i; item.even });
 167 ::
 168 If you want to control what type of collection is returned, use link::#-rejectAs::(function, class).
 169
 170 method::detect
 171 Answer the first item in the receiver for which strong::function:: answers link::Classes/True::. The function is passed two arguments, the item and an integer index.
 172 code::
 173 List[1, 2, 3, 4].detect({ arg item, i; item.even });
 174 ::
 175
 176 method::detectIndex
 177 Similar to link::#-detect:: but returns the index instead of the item itself.
 178 code::
 179 List[1, 2, 3, 4].detectIndex({ arg item, i; item.even });
 180 ::
 181
 182 method::inject
 183 In functional programming, the operation known as a fold.
 184 inject takes an initial value and a function and combines the elements of the collection by applying the function to the accumulated value and an element from the collection. The strong::function:: takes two arguments and returns the new value. The accumulated value is initialzed to strong::initialValue::.
 185 code::
 186 [1,2,3,4,5].inject(0, _+_); // 15
 187
 188 [1,2,3,4,5].inject(1, _*_); // 120
 189
 190 // same as .collect(_.squared)
 191 [1,2,3,4,5].inject([], {|a,b| a ++ b.squared }); // [ 1, 4, 9, 16, 25 ]
 192 [1,2,3,4,5].inject([], {|a,b| [b] ++ a ++ [b]}); // [ 5, 4, 3, 2, 1, 1, 2, 3, 4, 5 ]
 193 [1,2,3,4,5].inject([], {|a,b| a ++ b ++ a});
 194 [1,2,3,4,5].inject([], {|a,b| a ++ a ++ b});
 195 ::
 196
 197 method::any
 198 Answer whether strong::function:: answers link::Classes/True:: for any item in the receiver. The function is passed two arguments, the item and an integer index.
 199 code::
 200 List[1, 2, 3, 4].any({ arg item, i; item.even });
 201 ::
 202
 203 method::every
 204 Answer whether strong::function:: answers link::Classes/True:: for every item in the receiver. The function is passed two arguments, the item and an integer index.
 205 code::
 206 List[1, 2, 3, 4].every({ arg item, i; item.even });
 207 ::
 208
 209 method::count
 210 Answer the number of items for which strong::function:: answers link::Classes/True::. The function is passed two arguments, the item and an integer index.
 211 code::
 212 List[1, 2, 3, 4].count({ arg item, i; item.even });
 213 ::
 214
 215 method::occurrencesOf
 216 Answer the number of items in the receiver which are equal to anObject.
 217 code::
 218 List[1, 2, 3, 3, 4, 3, 4, 3].occurrencesOf(3);
 219 ::
 220
 221 method::sum
 222 Answer the sum of the results of strong::function:: evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.
 223 code::
 224 List[1, 2, 3, 4].sum;
 225 (0..8).sum { |i| 1 / (2 ** i) };
 226 ::
 227
 228 method::maxItem
 229 Answer the maximum of the results of strong::function:: evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.
 230 If function is nil, then answer the maximum of all items in the receiver.
 231 code::
 232 List[1, 2, 3, 4].maxItem({ arg item, i; item + 10 });
 233 ::
 234
 235 method::minItem
 236 Answer the minimum of the results of strong::function:: evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.
 237 If function is nil, then answer the minimum of all items in the receiver.
 238 code::
 239 List[1, 2, 3, 4].minItem({ arg item, i; item + 10 });
 240 ::
 241
 242 method::maxIndex
 243 Answer the index of the maximum of the results of strong::function:: evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.
 244 If function is nil, then answer the maximum of all items in the receiver.
 245 code::
 246 List[1, 2, 3, 4].maxIndex({ arg item, i; item + 10 });
 247 [3.2, 12.2, 13, 0.4].maxIndex;
 248 ::
 249
 250 method::minIndex
 251 Answer the index of the minimum of the results of strong::function:: evaluated for each item in the receiver. The function is passed two arguments, the item and an integer index.
 252 If function is nil, then answer the minimum of all items in the receiver.
 253 code::
 254 List[1, 2, 3, 4].minIndex({ arg item, i; item + 10 });
 255 List[3.2, 12.2, 13, 0.4].minIndex;
 256 ::
 257
 258 method::iter
 259 Returns a link::Classes/Routine:: that returns the elements one by one.
 260 code::
 261 r = Set[10, 2, -3, -4].iter;
 262 r.next;
 263 r.next;
 264 r.next;
 265 r.next; // nil.
 266 ::
 267
 268 subsection::Conversion
 269
 270 method::asBag
 271 Answer a link::Classes/Bag:: to which all items in the receiver have been added.
 272 code::
 273 List[1, 2, 3, 4].asBag;
 274 ::
 275
 276 method::asList
 277 Answer a link::Classes/List:: to which all items in the receiver have been added.
 278 code::
 279 Set[1, 2, 3, 4].asList;
 280 ::
 281
 282 method::asSet
 283 Answer a link::Classes/Set:: to which all items in the receiver have been added.
 284 code::
 285 List[1, 2, 3, 4].asSet;
 286 ::
 287
 288 method::asSortedList
 289 Answer a link::Classes/SortedList:: to which all items in the receiver have been added.
 290 code::
 291 List[2, 1, 4, 3].asSortedList;
 292 ::
 293
 294 method::powerset
 295 Returns all possible combinations of the collection's elements.
 296 code::
 297 Set[1, 2, 3].powerset;
 298
 299 // generate the von neumann ordinals. (warning: only count to four at maximum!)
 300 a = Set[];
 301 a = a.powerset;
 302 a = a.powerset;
 303 a = a.powerset;
 304
 305 u = { |set| set.unify }; // union (count down)
 306 n = { |set| set.powerset }; // powerset (count up)
 307 a = Set[]; // empty set (zero)
 308 n.(n.(a)); // two
 309 u.(n.(n.(a))) == n.(a); // two - one == one
 310 u.(u.(n.(n.(a)))) == u.(n.(a)); // two - two == one - one
 311 ::
 312
 313 method::flopDict
 314 Takes a collection of dictionaries and returns a single dictionary with arrays of all dictionaries' elements.
 315 If unbubble is link::Classes/True:: (default), and if one element is singular, the array is replaced by this element.
 316 code::
 317 [(degree: 7, x: 4), (degree: 8, x: 5), (degree: -2, dur: 2.5)].flopDict;
 318 [(degree: 7, x: 4), (degree: 8, x: 5), (degree: -2, dur: 2.5)].flopDict(false);
 319 ::
 320
 321 method::histo
 322 Returns a histogram of the collection by counting the number of values that fall into each slot of size (default: 100) subdivisions between min and max. If there are any values outside this range, it posts a note. If min or max is not given, the smallest (or largest value respectively) is used.
 323 code::
 324 { 1.0.linrand }.dup(10000).histo(1000).plot;
 325 { 8.rand }.dup(10000).histo(8).plot(discrete: true);
 326 ::
 327
 328 subsection::Writing to streams
 329
 330 method::printOn
 331 Print a representation of the collection to a stream.
 332
 333 method::storeOn
 334 Write a compileable representation of the collection to a stream.
 335
 336 method::printItemsOn
 337 Print a comma separated compileable representation of the items in the collection to a stream.
 338
 339 method::storeItemsOn
 340 Write a comma separated compileable representation of the items in the collection to a stream.
 341
 342 subsection::Set specific operations
 343
 344 method::sect
 345 Return the set theoretical intersection of this and strong::that::.
 346 code::
 347 a = [1, 2, 3]; b = [2, 3, 4, 5];
 348 sect(a, b);
 349 ::
 350
 351 method::union
 352 Return the set theoretical union of this and strong::that::.
 353 code::
 354 a = [1, 2, 3]; b = [2, 3, 4, 5];
 355 union(a, b);
 356 ::
 357
 358 method::difference
 359 Return the set of all items which are elements of this, but not of strong::that::.
 360 code::
 361 a = [1, 2, 3]; b = [2, 3, 4, 5];
 362 difference(a, b);
 363 ::
 364
 365 method::symmetricDifference
 366 Return the set of all items which are not elements of both  this and strong::that::.
 367 this -- that
 368 code::
 369 a = [1, 2, 3]; b = [2, 3, 4, 5];
 370 symmetricDifference(a, b);
 371 ::
 372
 373 method::isSubsetOf
 374 Returns link::Classes/True:: if all elements of this are also elements of strong::that::
 375 code::
 376 a = Set[1, 2, 3, 4];
 377 Set[1, 2].isSubsetOf(a); // true
 378 Set[1, 5].isSubsetOf(a); // false
 379 ::