HelpSource/Classes/IdentityBag.schelp

   1 CLASS::IdentityBag
   2 summary::A Bag according to identity
   3 categories::Collections>Unordered
   4
   5 DESCRIPTION::
   6 An IdentityBag 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::identity::).
   7
   8 The contents of a IdentityBag are unordered. You must not depend on the order of items in a set.
   9
  10 INSTANCEMETHODS::
  11
  12 private::setDictionary
  13
  14 subsection::Adding and Removing
  15
  16 method::add
  17 Add anObject to the Bag. A Bag may contain multiple entries of the same object.
  18 code::
  19 IdentityBag[1, 2, 3].add(4);
  20 IdentityBag[1, 2, 3].add(3);
  21 IdentityBag["abc", "def", "ghi"].add("jkl");
  22 IdentityBag["abc", "def", "ghi"].add("def");
  23 ::
  24
  25 method::remove
  26 Remove anObject from the IdentityBag.
  27 code::
  28 IdentityBag[1, 2, 3].remove(3);
  29 ::
  30
  31 method::contents
  32 Returns the dictionary that stores the objects in pairs (obj -> numberOfObjects)
  33 code::
  34 IdentityBag[\a, \b, \c, \c].contents;
  35 ::
  36
  37 subsection::Iteration
  38
  39 method::do
  40 Evaluates function for each item in the IdentityBag.
  41 The function is passed two arguments, the item and an integer index.
  42 code::
  43 IdentityBag[1, 2, 3, 300].do({ arg item, i; item.postln });
  44 ::
  45
  46 ::
  47
  48 section::Difference between Bag and IdentityBag
  49 code::
  50 // the two strings are equal, but not identical
  51 "something" == "something"; // true
  52 "something" === "something" // false
  53
  54 a = Bag.new;
  55 a.add("something");
  56 a.add("something");
  57 a.contents; // only one object in the bag really
  58
  59 a = IdentityBag.new;
  60 a.add("something");
  61 a.add("something");
  62 a.contents; // two objects in the bag
  63 ::