HelpSource/Classes/MultiLevelIdentityDictionary.schelp

   1 CLASS::MultiLevelIdentityDictionary
   2 summary::tree of dictionaries
   3 related:: Classes/IdentityDictionary
   4 categories:: Collections>Unordered
   5
   6 DESCRIPTION::
   7 A tree of IdentityDictionaries. Addresses within the tree are specified with a series of keys. link::Classes/Library:: is its most useful subclass.
   8
   9 INSTANCEMETHODS::
  10
  11 private::add, remove, removeFail, prChooseFrom, prPutTree, leaves, prNestedValuesFromDict, prRemoveAtPathRecursive, storeOn, printOn
  12
  13 method::at
  14 Retrieves a leaf node or nil if not found.
  15
  16 method::put
  17 Puts the item as a leaf node, internally creating new branches as needed to accommodate the list of keys.
  18
  19 method::choose
  20 Choose a branch at each level, descend the tree until a leaf is chosen.
  21 By using arguments strong::key1, key2 ... keyN::, one can start at an address within the tree, descend the tree until a leaf is chosen.
  22
  23 method::putTree
  24 A way to insert objects into the tree with a syntax similar to the organization of the tree itself.
  25 code::
  26 //pseudo code:
  27 putTree(key1,[
  28         key2a, item1-2a,
  29         key2b, item1-2b,
  30         [
  31                 key3, item1-3
  32         ] // etc...
  33 ]);
  34 ::
  35
  36 method::removeAt
  37 Remove only the item located by the path.
  38
  39 method::removeEmptyAt
  40 Remove the item located by the path. This might make the item's parent dictionary empty. In that case, it will remove the parent and continue up the chain, removing empty dictionaries as it goes. This is slower but cleaner.
  41
  42 EXAMPLES::
  43
  44 code::
  45 // Example of the difference between removeAt and removeEmptyAt
  46
  47 m = MultiLevelIdentityDictionary.new;
  48 m.put(\a, \b, \c, 1);
  49
  50 m.removeAt(\a, \b, \c);
  51 m       // note, \a and \b dictionaries remain
  52
  53 m.put(\a, \b, \c, 2);
  54 m.removeEmptyAt(\a, \b, \c);
  55 m       // now the entire MultiLevelIdentityDictionary is empty
  56 ::