home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-2.iso / Developer / resources / libraries / libcoll.README < prev    next >
Encoding:
Text File  |  1993-05-21  |  5.9 KB  |  146 lines
  1. Alpha Release of the Collection Library for GNU Objective-C
  2.  
  3. WARNING: This library has not been tested, and I would be surprised if
  4. it were usable at this point.  I am making it public now in order to
  5. get feedback on design issues.
  6.  
  7. ------------------------------------------------------------------
  8. * Where can you get it?
  9.  
  10. By anonymous ftp at iesd.auc.dk:pub/ObjC/libcoll-??????.tar.z,
  11. where ?????? is some string of numbers specifying its date.
  12.  
  13. ------------------------------------------------------------------
  14. * What is the Collection library?
  15.  
  16. It's a library of Objective-C objects with similar functionality to
  17. Smalltalk's Collection objects.  It includes: Set, Bag, Array,
  18. LinkedList, LinkList, CircularArray, Queue, Stack, SortedArray,
  19. MappedCollector, GapArray and DelegateList.  
  20.  
  21. Outside of its main heirarchy it also includes List, HashTable and
  22. Storage objects compatible with NeXT's objects of the same name.
  23.  
  24. The library is built around several protocols: Here are some explanatory
  25. comments from the protocol .h files:
  26.  
  27.    The <Collecting> protocol is root of the collection protocol heirarchy. 
  28.    The <Collecting> protocol defines the most general interface to a
  29.    collection of elements.  Elements can be added, removed, and replaced.
  30.    The contents can be tested, enumerated, and copied with various
  31.    modifications.  Elements may be objects, or any C type included in the 
  32.    "elt" union given below, but all elements of a collection must be of
  33.    the same C type.
  34.    [NOTE: for examples see Set and Bag.]
  35.  
  36.    The <KeyedCollecting> protocol inherits from the <Collecting> protocol.
  37.    The <KeyedCollecting> protocol defines the interface to a
  38.    collection of elements that are accessible by a key, where the key is
  39.    some unique element.  Pairs of (key element, content element) may be
  40.    added, removed and replaced.  The the key and value contents may be
  41.    tested, enumerated and copied.  
  42.    [NOTE: for examples see Dictionary and MappedCollector.]
  43.  
  44.    The <IndexedCollecting> protocol inherits from the 
  45.    <KeyedCollecting> protocol.
  46.    The <IndexedCollecting> protocol defines the interface to a
  47.    collection of elements that are accessible by a key that is an index,
  48.    where the indeces in a collection are a contiguous series of unsigned
  49.    integers beginning at 0.  This is the root of the protocol heirarchy
  50.    for all collections that hold their elements in some order.  Elements
  51.    may be accessed, inserted, replaced and removed by their index.  
  52.    [NOTE: for examples see Array and LinkList.]
  53.  
  54.    The <ComparedCollecting> protocol inherits from the 
  55.    <IndexedCollecting> protocol.
  56.    The <ComparedCollecting> protocol defines the interface to a
  57.    collection of elements whose sequence is affected by some comparison
  58.    operator.
  59.    [NOTE: for an example see SortedArray.]
  60.  
  61.    The <ListLinking> protocol defines the interface to an object
  62.    that may be an element in a LinkList.  LinkList is a collection
  63.    object based on a doubly linked list.
  64.    [NOTE: for an example see ListLink.]
  65.  
  66.  
  67. Here is the object inheritance heirarchy.  All collection abtract
  68. superclasses (classes which are not usable without subclassing) end
  69. with "Collection"; all protocols end with "ing"; all collection
  70. protocols end with "Collecting".
  71.  
  72.    Collection <Collecting>
  73.        Set
  74.            Bag
  75.        KeyedCollection <KeyedCollecting>
  76.            Dictionary
  77.            MappedCollector
  78.            IndexedCollection <IndexedCollecting>
  79.                Array
  80.                    Stack
  81.                    GapArray
  82.                    CircularArray
  83.                        Queue
  84.                    SortedArray <ComparedCollecting>
  85.                LinkList
  86.                LinkedList
  87.     ListLink <ListLinking>
  88.         EltListLink
  89.     DelegateList
  90.     HashTable
  91.     List
  92.     Storage
  93.  
  94.  
  95. ------------------------------------------------------------------
  96. * The design philosophy.
  97.  
  98. Objective C is not Smalltalk.  Differences that matter to the
  99. Collection heirarchy:
  100.  
  101. - There can be only one set of argument types with each selector.
  102. (For instance in Objective C we can't have "-(double)data" and
  103. "-(char)data".  I can't stand it when some library that I'm forced to
  104. load already defines a selector that I want to use with different
  105. types.)  This isn't an issue in Smalltalk because everything is an
  106. object. 
  107.  
  108. * I make the Collection method names a little more descriptive, while
  109. keeping them close to Smalltalk.  (For instance I think there is a
  110. good reason for using "-addObject:" instead of "-add:")
  111.  
  112. - We will want collections of int's, float's, and other non-Objects.
  113. Using Objective C wrappers around these C primitive types (i.e.
  114. Integer and Float objects) is not an efficient enough option for all
  115. cases. 
  116.  
  117. * We could create two parallel heirarchies, one for Objects and one
  118. for elements passed as void*, but since so much of the functionality
  119. overlaps, I have merged them, and it doesn't actually look all that
  120. bad.
  121.  
  122. - Objective C doesn't have Smalltalk Blocks.  
  123.  
  124. * Passing selectors and pointers to functions are both reasonable
  125. substitutes.  I make both options available.  They are distinguished
  126. as "-detectByCalling:" and "-detectByPerforming:", for example.
  127.  
  128. - Smalltalk does automatic garbage collection; Objective C doesn't.
  129.  
  130. * I think it should be made obvious which methods allocate a new
  131. object.  Hence "-shallowCopyAs:[Bag class]" instead of 
  132. "as:[Bag class]", and "-shallowCopySelect..." instead of "-select...".
  133.  
  134. - We have usable Collection classes (Set, Bag, Array, etc) with
  135. functionality matching Smalltalk's objects, but there are good
  136. reasons for not having the abstract superclass structure match
  137. Smalltalk exactly.
  138.  
  139. ------------------------------------------------------------------
  140. * If you have any suggestions or bug reports, please contact:
  141.  
  142. R. Andrew McCallum            ARPA: mccallum@cs.rochester.edu
  143. Computer Science Department   UUCP: uunet!cs.rochester.edu!mccallum
  144. University of Rochester       VOX: (716) 275-2527
  145. Rochester, NY  14627-0226     FEET: CSB  Rm. 625
  146.