home *** CD-ROM | disk | FTP | other *** search
/ PC Media 7 / PC MEDIA CD07.iso / share / prog / cm / cm.doc < prev    next >
Encoding:
Text File  |  1994-08-31  |  7.8 KB  |  140 lines
  1.                 Compendium - C++ Container Class Library
  2.      Copyright (C) 1992-1994, Glenn M. Poorman, All rights reserved
  3. ------------------------------------------------------------------------------
  4.  
  5.  
  6.                        Compendium  Version 1.1
  7.                         C++ Container Classes
  8.  
  9.  
  10. Compendium is a library of container classes for C++ development.  This
  11. library provides a full set of both object based (smalltalk-like) containers
  12. and template based containers.  Compendium works with DOS, Windows, and
  13. WIN32 programs using Borland C++.  There is also a unix version available
  14. which has been compiled and tested using cfront on Sun, HP, and SGI work-
  15. stations as well as the xlC compiler on IBM.  Future ports to other compilers
  16. will happen as requests and resources permit.
  17.  
  18. Object Based Containers
  19. -----------------------
  20. The object based library is a full set of containers where the objects
  21. to be added must derive (directly or indirectly) from a common base class
  22. called "CmObject".  These containers take, as input, pointers to these
  23. objects.  The objects are not copied, only the pointers.  This means that
  24. the objects must be dynamically allocated using the "new" operator.  All
  25. of the object based containers derive from the class "CmContainer" and
  26. share certain core behavior.  For example, and object can be added to any
  27. container using the function "add" and removed using the function "remove".
  28. The virtual functions in "CmContainer" shared by all containers are:
  29.  
  30.   CmObject*   operator[] (int idx) const;    // Return object at index.
  31.   unsigned    size       () const;           // Return container size.
  32.   Bool        add        (CmObject*);        // Add object to container.
  33.   Bool        remove     (CmObject*);        // Remove first equal object.
  34.   CmObject*   lookup     (CmObject*) const;  // Return pointer to equal.
  35.   Bool        contains   (CmObject*) const;  // See if equal object is in.
  36.   unsigned    occurrences(CmObject*) const;  // Return number of equal objects.
  37.   void        removeAll  ();                 // Remove all objects.
  38.   Bool        isEmpty    () const;           // See if container is empty.
  39.   CmIterator* newIterator() const;           // Create and return an iterator.
  40.  
  41. Every type of container also defines an iterator class.  An iterator is an
  42. object used to cycle through the contents of a container.  All iterator
  43. classes derive from the class "CmIterator" and share the same behavior.
  44. The iterator functions are:
  45.  
  46.   Bool      done    () const;  // See if iterator reached container limit.
  47.   CmObject* next    ();        // Return object and advance to next.
  48.   CmObject* previous();        // Return object and backup to previous.
  49.   CmObject* current () const;  // Return current object.
  50.   void      first   ();        // Move iterator to first object.
  51.   void      last    ();        // Move iterator to last object.
  52.  
  53. Remembering that the container contains pointers to objects that you
  54. allocate, what happens when a container is deleted.  The container function
  55. "ownsObjects" allows you to set whether or not a container owns it's objects.
  56. A container that owns it's objects will delete them when the container is
  57. destroyed or when objects are removed.  Also a container that owns it's
  58. objects will copy the objects when the container is copied.  Conversely,
  59. a container that does not own it's objects will never delete them and
  60. when the container is copied, only the pointers will be copied leaving
  61. two containers pointing to the same objects.  Use this carefully.
  62.  
  63. As mentioned previously, any object to be inserted into a container must
  64. derive from "CmObject".  The class "CmObject" has pure virtual functions
  65. that must be defined for every class.  These are:
  66.  
  67.   char*     isA     () const;             // Return the class name.
  68.   Bool      isA     (const char*) const;  // See if input matches class name.
  69.   Bool      isTypeOf(const char*) const;  // See if input is parent class name.
  70.   CmObject* newCopy () const;             // Create a copy and return pointer.
  71.  
  72. These functions can be defined in the derived class simply by making a
  73. one line macro call.  The macro is "CMOBJECT_DEFINE(class, parent)" where
  74. class is the class name and parent is the parent class name.  The class
  75. "CmObject" also contains several virtual functions which can be optionally
  76. redefined to control container behavior.  These are:
  77.  
  78.   Bool isEqual(CmObject*) const;  // See if input object is equal to this.
  79.   int  compare(CmObject*) const;  // Compare input object to this.
  80.                                   // 0-equal, -1-this<input, 1-this>input
  81.   unsigned hash(unsigned) const;  // Perform hash with input table size.
  82.  
  83. Template Based Containers
  84. -------------------------
  85. The Compendium library also provides a full set of template based containers.
  86. These containers were designed, using the C++ template mechanism, to hold
  87. any kind of data including the standard C types.  The only catch is that any
  88. data type to be added to a container template must have all of the lexical
  89. operators defined (<, <=, >, >=, ==, !=).  The template containers all take
  90. item references as input and the items are copied into the container.  This
  91. means that user defined types must have copy constructors and assignment
  92. operators defined.  As with the object based containers, all template based
  93. containers derive from a common base class called "CmTContainer<T>" where T
  94. denotes the data type.  The virtual functions in "CmTContainer<T>" shared by
  95. all template containers are:
  96.  
  97.   const T& operator[] (int idx) const;   // Return item at index.
  98.   unsigned size       () const;          // Return container size.
  99.   Bool     add        (const T&);        // Add item to container.
  100.   Bool     remove     (const T&);        // Remove first equal item.
  101.   const T& lookup     (const T&) const;  // Return first equal item.
  102.   Bool     contains   (const T&) const;  // See if equal item exists.
  103.   unsigned occurrences(const T&) const;  // Return number of equal items.
  104.   void     removeAll  ();                // Remove all items.
  105.   Bool     isEmpty    () const;          // See if container is empty.
  106.   CmTIterator<T>* newIterator() const;   // Create and return an iterator.
  107.  
  108. Every type of container template also defines an iterator template.  An
  109. iterator is an object used to cycle through the contents of a container.
  110. All iterator templates derive from the class "CmTIterator<T>" and share
  111. the same behavior.  The iterator functions are:
  112.  
  113.   Bool     done    () const;    // See if iterator reached container limit.
  114.   const T& next    ();          // Return item and advance to next.
  115.   const T& previous();          // Return item and backup to previous.
  116.   const T& current () const;    // Return current item.
  117.   void     restart ();          // Restart iteration at beginning.
  118.   void     toEnd   ();          // Move iterator to last item.
  119.  
  120. See the file "CLASSES.LST" for the complete Compendium class list.  And
  121. remember that registering Compendium gets you a complete programmer's
  122. guide and reference manual.  For registration information, see the file
  123. "READ.ME".
  124.  
  125. Improvements and Changes from version 1.0
  126. -----------------------------
  127. * several small bug fixes discovered in-house and by users,
  128. * improved performance in object I/O from the reserve,
  129. * added iterator functionality,
  130. * Max, min, and abs template functions.
  131. * Looping macros.
  132. * New support for Sun (Solaris), HP (HP-UX), SGI (IRIX), and IBM (AIX).
  133. * a better installation mechanism.
  134. * New "firstThat" functions in "CmContainer" and "CmReserve" class.
  135. * Iterator functions "restart" and "toEnd" are now "first" and "last".
  136. * Output arguments of several template functions in both "CmTContainer"
  137.   and "CmTIterator" were changed from "T" to "const T&".
  138. * Remove "isOld" and "isNew" functions from "CmReserve" and added a
  139.   single "exists" function.
  140.