HelpSource/Classes/Bag.schelp

   1 CLASS::Bag
   2 summary::Unordered collection of objects
   3 related::Classes/IdentityBag, Classes/Set
   4 categories::Collections>Unordered
   5
   6 DESCRIPTION::
   7 A Bag is an unordered collection of objects. In some languages it is referred to as a counted set. A Bag keeps track of the number of times objects are inserted and requires that objects be removed the same number of times. There is only one instance of an object in a Bag even if the object has been added to the Bag multiple times (test is for strong::equality::)
   8
   9 Most of Bag's methods are inherited from Collection.
  10 The contents of a Bag are unordered. You must not depend on the order of items in a set.
  11
  12 CLASSMETHODS::
  13
  14 method::new
  15 Creates a Bag with an initial capacity for strong::n:: objects.
  16
  17 INSTANCEMETHODS::
  18
  19 private::setDictionary
  20
  21 method::contents
  22 Returns the dictionary that stores the objects in pairs (obj -> numberOfObjects)
  23 code::
  24 Bag["a", "b", "c", "c"].contents;
  25 ::
  26 returns:: link::Classes/Dictionary::
  27
  28 method::itemCount
  29 Count the number of strong::item::s.
  30 code::
  31 Bag[1, 2, 2, 3, 300, 2].itemCount(2);
  32 ::
  33
  34 subsection::Adding and Removing
  35
  36 method::add
  37 Add an object to the Bag. A Bag may contain multiple entries of the same object.
  38 code::
  39 Bag[1, 2, 3].add(4).postln;
  40
  41 Bag[1, 2, 3].add(3).postln;
  42
  43 Bag["abc", "def", "ghi"].add("jkl").postln;
  44
  45 Bag["abc", "def", "ghi"].add("def").postln;
  46 ::
  47
  48 method::remove
  49 Remove an object from the Bag.
  50 code::
  51 Bag[1, 2, 3].remove(3).postln;
  52 ::
  53
  54 subsection::Iteration
  55
  56 method::do
  57 Evaluates strong::function:: for each item in the Bag.
  58 The function is passed two arguments, the item and an integer index.
  59 code::
  60 Bag[1, 2, 3, 300].do({ arg item, i; item.postln });
  61
  62 Bag[1, 2, 2, 3, 300].do({ arg item, i; item.postln });
  63 ::
  64 argument::function
  65 args to function: item, i
  66
  67 method::countsDo
  68 Evaluates strong::function:: for each unique item in the Bag along with that item's count.
  69 The function is passed two arguments, the item, the quantity of that item in the Bag and an integer index.
  70 code::
  71 Bag[1, 2, 3, 300].countsDo({ arg item, count, i; [item,count].postln });
  72
  73 Bag[1, 2, 2, 3, 300].countsDo({ arg item, count, i; [item,count].postln });
  74 ::
  75
  76 subsection::Testing
  77
  78 method::includes
  79 Answer whether an object is contained in the Bag.
  80 code::
  81 Bag[1, 2, 3, 4].includes(3);
  82 ::
  83 returns:: link::Classes/Boolean::
  84
  85 EXAMPLES::
  86
  87 subsection::Difference between Bag and IdentityBag:
  88 code::
  89 // the two strings are equal, but not identical
  90 "something" == "something"; // true
  91 "something" === "something" // false
  92
  93 a = Bag.new;
  94 a.add("something");
  95 a.add("something");
  96 a.contents; // only one object in the bag really
  97
  98 a = IdentityBag.new;
  99 a.add("something");
 100 a.add("something");
 101 a.contents; // two objects in the bag
 102 ::
 103 argument::function
 104 args to function: item, count, i