HelpSource/Classes/IdentitySet.schelp

   1 CLASS::IdentitySet
   2 summary::a set according to identity
   3 related::Classes/List, Classes/Dictionary
   4 categories::Collections>Unordered
   5
   6 DESCRIPTION::
   7 An IdentitySet is a collection of objects, no two of which are the same object (aka. "identical").
   8 Most of its methods are inherited (see link::Classes/Collection:: and link::Classes/Set:: classes).
   9 The contents of an IdentitySet are unordered. You must not depend on the order of items in an IdentitySet.
  10 For an ordered set, see link::Classes/OrderedIdentitySet::.
  11
  12 IdentitySets are faster than Sets because testing for identity is much faster than testing for equality. Different classes may implement equality in different ways, but identity can be determined just by comparing the object addresses. This allows some methods of IdentitySet to be implemented
  13 by fast primitives.
  14
  15 INSTANCEMETHODS::
  16
  17 subsection::Adding and Removing
  18
  19 method::add
  20 Add anObject to the IdentitySet. An object which is equal to an object already in the IdentitySet will not be added.
  21 code::
  22 IdentitySet[1, 2, 3].add(4);
  23 IdentitySet[1, 2, 3].add(3);
  24 // the two strings are equal but not identical
  25 IdentitySet["abc", "def", "ghi"].add("def");
  26 // symbols are guaranteed to be identical if they are equal
  27 IdentitySet['abc', 'def', 'ghi'].add('def');
  28 IdentitySet['abc', 'def', 'ghi'].add('jkl');
  29 ::
  30
  31 method::remove
  32 Remove anObject from the IdentitySet.
  33 code::
  34 IdentitySet[1, 2, 3].remove(3);
  35 ::
  36
  37 subsection::Iteration
  38
  39 method::do
  40 Evaluates function for each item in the IdentitySet. You must not depend on the order of items. The function is passed two arguments, the item and an integer index.
  41 code::
  42 IdentitySet[1, 2, 3, 300].do { |item, i| item.postln };
  43 ::
  44
  45 subsection::Finding an element
  46
  47 method::findMatch
  48 Returns item if it is in the collection, otherwise returns nil.
  49 code::
  50 a = IdentitySet[1, 2, 3, 300];
  51 a.findMatch(1);
  52 a.findMatch(1.5);
  53 ::
  54
  55 EXAMPLES::
  56
  57 code::
  58 // scanFor is fairly efficient. compare the following benchmarks:
  59
  60 // comparison of array indexing and identity set lookup
  61 (
  62 f = { |n=4|
  63         var x, y, i;
  64         x = (0..n);
  65         y = x.as(IdentitySet);
  66         i = x.choose;
  67         bench { 100.do { x[i] } };
  68         bench { 100.do { y.scanFor(i) } };
  69 }
  70 );
  71
  72 f.(4)
  73 f.(8)
  74 f.(100)
  75 f.(10000)
  76 ::
  77
  78 code::
  79 // you can use IdentitySet to efficiently remove identical duplicates from an array:
  80
  81 (
  82 var e, f, g, h;
  83 e = "such"; f = "fallacy"; g = "is"; h = "common";
  84 a = [e, e, f, g, e, h, e];
  85 );
  86 a.as(IdentitySet);      // convert to set
  87 a.as(Set).as(Array);    // and convert back
  88
  89 // note that the following behaves differently:
  90 a = [ "such", "such", "fallacy", "is", "such", "common", "such" ]
  91 a.as(IdentitySet);      // convert to set. All elements are still here.
  92                         // Different strings may look the same, but be different objects.
  93
  94 // To remove equals in stead of identicals, use Set:
  95 a.as(Set);
  96 ::