home *** CD-ROM | disk | FTP | other *** search
/ The Devil's Doorknob BBS Capture (1996-2003) / devilsdoorknobbbscapture1996-2003.iso / Dloads / OTHERUTI / TCPP10-8.ZIP / CLASSSRC.ZIP / CLASSLIB.DOC < prev    next >
Text File  |  1990-09-26  |  56KB  |  1,647 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                Turbo C++ Class Library Definition
  8.  
  9.             Copyright (C) 1990, Borland International
  10.  
  11.  
  12.                                                                      i
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                           Contents
  23.  
  24.  
  25.  
  26.      Chapter 1  Abstract Classes in an Object-Based
  27.                 Hierarchy                                  5
  28.         1.1  Class Object  . . . . . . . . . . . . . . . . 5
  29.         1.2  Class Error . . . . . . . . . . . . . . . . . 6
  30.         1.3  Class Sortable  . . . . . . . . . . . . . . . 7
  31.         1.4  Class Association . . . . . . . . . . . . . . 8
  32.  
  33.      Chapter 2  Container Classes                          9
  34.         2.1  Object Ownership  . . . . . . . . . . . . . . 9
  35.         2.2  Class Container . . . . . . . . . . . . . .  10
  36.            2.2.1  Function Prototype for Arguments to
  37.                   forEach  . . . . . . . . . . . . . . .  10
  38.            2.2.2  Function Prototype for Arguments to
  39.                   firstThat  . . . . . . . . . . . . . .  10
  40.         2.3  Sequence Grouping . . . . . . . . . . . . .  11
  41.            2.3.1  Class Stack  . . . . . . . . . . . . .  11
  42.            2.3.2  Class Queue  . . . . . . . . . . . . .  12
  43.            2.3.3  Class Deque  . . . . . . . . . . . . .  12
  44.  
  45.      Chapter 3  Collection Hierarchy                      15
  46.         3.1  Class Collection  . . . . . . . . . . . . .  15
  47.         3.2  Derived Classes of Collection . . . . . . .  16
  48.            3.2.1  Unordered Collections  . . . . . . . .  16
  49.               3.2.1.1  Class HashTable . . . . . . . . .  16
  50.               3.2.1.2  Class Bag . . . . . . . . . . . .  17
  51.               3.2.1.3  Class Set . . . . . . . . . . . .  18
  52.               3.2.1.4  Class Dictionary  . . . . . . . .  18
  53.               3.2.1.5  Class List  . . . . . . . . . . .  19
  54.               3.2.1.6  Class DoubleList  . . . . . . . .  19
  55.            3.2.2  Ordered Collections  . . . . . . . . .  20
  56.               3.2.2.1  Class AbstractArray . . . . . . .  21
  57.               3.2.2.2  Class Array . . . . . . . . . . .  21
  58.               3.2.2.3  Class SortedArray . . . . . . . .  22
  59.  
  60.      Chapter 4  Classes in the ContainerIterator
  61.                 Hierarchy                                 25
  62.  
  63.      Chapter 5  Class Library Directory Stucture          29
  64.         5.1  Directory INCLUDE . . . . . . . . . . . . .  29
  65.         5.2  Directory SOURCE  . . . . . . . . . . . . .  29
  66.         5.3  Directory LIB . . . . . . . . . . . . . . .  30
  67.         5.4  Directory EXAMPLES  . . . . . . . . . . . .  30
  68.  
  69.  
  70.                                                                     ii
  71.  
  72.  
  73.  
  74.      Chapter 6  Conventions Used In Class Libraries       31
  75.         6.1  File Naming . . . . . . . . . . . . . . . .  31
  76.         6.2  Source Naming   . . . . . . . . . . . . . .  31
  77.         6.3  Commenting Style  . . . . . . . . . . . . .  32
  78.            6.3.1  Module Header  . . . . . . . . . . . .  32
  79.            6.3.2  Dependencies . . . . . . . . . . . . .  32
  80.            6.3.3  Type Header  . . . . . . . . . . . . .  33
  81.            6.3.4  Function Header  . . . . . . . . . . .  33
  82.            6.3.5  Body Comments  . . . . . . . . . . . .  34
  83.  
  84.      Index                                                35
  85.  
  86.  
  87.  
  88.                                                                      2
  89.  
  90.  
  91.                                                                      3
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.                           Introduction
  102.  
  103.  
  104. This document may be read on-line or printed.   To  increase  the
  105. readability of the printed form,  we  have  included  page breaks
  106. between chapters.  When reading the document in its on-line form,
  107. you may see the page breaks as the character '^L'.
  108.  
  109. This document is an  introductory  guide  to  the Turbo C++ class
  110. libraries.  In this  document,  we  assume  that you are familiar
  111. with the syntax and semantics of C++ and with the  basic concepts
  112. of object-oriented  programming.  If you want more information on
  113. Turbo C++, see chapters 5 and 6 and the bibliography in the Turbo
  114. C++ manual Getting Started and chapters 1 and 3 in the  Turbo C++
  115. Programmer's Guide.
  116.  
  117. The lists of class  members  are for general reference only.  For
  118. the exact contents  of  each class, including private members and
  119. the types and parameters for members, see the source code itself.
  120.  
  121. The Turbo C++ class library defines a basic set of classes.   You
  122. can use these classes as they  are,  or you can extend and expand
  123. them to produce an object-oriented software  package  specific to
  124. your needs.
  125.  
  126. The  set  of classes is made up of two trees.   These  trees  are
  127. rooted by the abstract base classes Object and ContainerIterator.
  128. Each of these base  classes  is explored in a separate chapter in
  129. this document.
  130.  
  131.  
  132.                                                                      4
  133.  
  134.  
  135.                                                                      5
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.                             Chapter 1
  146.  
  147.           Abstract Classes in an Object-Based Hierarchy
  148.  
  149.  
  150. An object-based hierarchy  includes  data  items  derived  from a
  151. single  abstract  base  class.  In the Turbo C++ class libraries,
  152. the class Object serves as the root the hierarchy.   This chapter
  153. describes  the characteristics of the class  Object  and  of  the
  154. abstract classes derived from this class.
  155.  
  156. An abstract class is one from which you can create other classes,
  157. but one from which you  would not normally create usable objects.
  158. Conversely, a  non-abstract class, or instance class, is one from
  159. which you can create usable objects.  An example of this class is
  160. the String class.  In other words, instance classes are  one step
  161. removed from  usable objects, whereas abstract classes are two or
  162. more steps removed from usable objects.
  163.  
  164.  
  165. 1.1  Class Object
  166.  
  167.  
  168. Since Object is  an  abstract  class,  there are no data items of
  169. this type.  Since most data items are derived from  this abstract
  170. class,  however,  the  class  provides  a  basic   mechanism  and
  171. structure for  type checking and encapsulation.  The class Object
  172. provides a minimal set definition  for what a derived object must
  173. do.  An object must:
  174.  
  175.    1.  Return the class to which an object belongs.    The member
  176.        function isA() does this.
  177.  
  178.    2.  Return a  character representation of the class name.  The
  179.        member function nameOf() does this.
  180.  
  181.    3.  Display the contents of an object in a format suitable for
  182.        that object. The member function printOn() does this.
  183.  
  184.    4.  Return  a  unique  key  based  on the object.  The  member
  185.        function hashValue() does this.
  186.  
  187.    5.  Iterate through each part  which  makes  up an object. The
  188.        member function forEach() does this.
  189.  
  190.    6.  Find  the  first  or  last  part  or  whole  object  which
  191.        satisfies  a  given   condition.    The  member  functions
  192.        firstThat() and lastThat() do this.
  193.  
  194.  
  195.                                                                      6
  196.  
  197.  
  198.  
  199.    7.  Determine whether the object is equal  to  another object.
  200.        The member function isEqual() provides this capability.
  201.  
  202.    8.  Determine whether the object can be  sorted,  i.e. whether
  203.        it  is  derived  from  the  class  Sortable.   The  member
  204.        function isSortable() does this.  For more  information on
  205.        class Sortable, see the section entitled Class Sortable on
  206.        page 7.
  207.  
  208.    9.  Determine whether the object is  part  of  an association,
  209.        i.e. whether it is  derived  from  the  class Association.
  210.        The member function isAssociation  does  this.    For more
  211.        information on class Association, see the section entitled
  212.        Class Association on page 7.
  213.  
  214.   10.  Construct, destroy, and copy on to another object.
  215.  
  216.   11.  Allocate a new object.
  217.  
  218. The implementation of these functions is provided by each derived
  219. class; those  implementations  identify  that  class.  The  class
  220. Object has the following public members:
  221.  
  222. Data members:
  223.    ZERO
  224.  
  225. Public member functions:
  226.    isA
  227.    nameOf
  228.    hashValue
  229.    isEqual
  230.    isSortable
  231.    isAssociation
  232.    operator new
  233.    forEach
  234.    firstThat
  235.    lastThat
  236.    printOn
  237.  
  238. The  parameters  to  each of these member functions are listed in
  239. the header file for  each  class.    The three functions forEach,
  240. firstThat,  and  lastThat  take a pointer  to  a  function  as  a
  241. parameter.  The prototypes for  these functions is listed on page
  242. 10.
  243.  
  244.  
  245. 1.2  Class Error
  246.  
  247.  
  248. The class Error is a special instance class of the  class Object.
  249. There  is  exactly  one  instantiation  of  class  Error,  namely
  250. theErrorObject. Pointing to  this  global  object  is  the static
  251. object  pointer   Object::ZERO.   The   macro   NOOBJECT  defines
  252. Object::ZERO. The operator Object::operator new returns a pointer
  253.  
  254.  
  255.                                                                      7
  256.  
  257.  
  258.  
  259. to theErrorObject if an attempt  to allocate an object fails. You
  260. may test the return value of the new operator against NOOBJECT to
  261. see whether the allocation failed.
  262.  
  263. Derived from:  Object
  264.  
  265. Public member functions:
  266.    isA
  267.    nameOf
  268.    hashValue
  269.    printOn
  270.    isEqual          Inherited from Object.
  271.    isSortable       Inherited from Object.
  272.    isAssociation    Inherited from Object.
  273.    operator new     Inherited from Object.
  274.    forEach          Inherited from Object.
  275.    firstThat        Inherited from Object.
  276.    lastThat         Inherited from Object.
  277.  
  278.  
  279. 1.3  Class Sortable
  280.  
  281.  
  282. The first abstract class consists of the class  of  objects which
  283. are  sortable.  Membership  in  this  class is limited  to  those
  284. objects that can be tested for order. You can derive objects from
  285. it and place these derived objects into ordered collections, such
  286. as  trees.  An  object which has  been  derived  from  the  class
  287. Sortable must define isLessThan, in addition  to  those functions
  288. required of the class  Object.  (Remember  that class Sortable is
  289. derived from class Object and therefore  inherits  the properties
  290. of that class.)
  291.  
  292. Derived from: Object
  293.  
  294. Public member functions:
  295.    isSortable
  296.    isLessThan
  297.    isA              Inherited from Object
  298.    nameOf           Inherited from Object.
  299.    isEqual          Inherited from Object.
  300.    hashValue        Inherited from Object.
  301.    isAssociation    Inherited from Object.
  302.    operator new     Inherited from Object.
  303.    forEach          Inherited from Object.
  304.    firstThat        Inherited from Object.
  305.    lastThat         Inherited from Object.
  306.    printOn          Inherited from Object.
  307.  
  308.  
  309.                                                                      8
  310.  
  311.  
  312.  
  313. 1.4  Class Association
  314.  
  315.  
  316. Like  the  abstract  class  Sortable,  the  class  Association is
  317. another example of a  class  of objects which are used as members
  318. of another object (in this case, a Dictionary class object).  For
  319. more  information  on  the  class  Dictionary,  see  the  section
  320. entitled Class Dictionary.    The  class  Association  provides a
  321. logical grouping for a key and a value.
  322.  
  323. Derived from:  class Object
  324.  
  325. Public member functions:
  326.    isA
  327.    nameOf
  328.    hashValue
  329.    printOn
  330.    isEqual
  331.    isAssociation
  332.    key
  333.    value
  334.    isSortable       Inherited from Object.
  335.    operator new     Inherited from Object.
  336.    forEach          Inherited from Object.
  337.    firstThat        Inherited from Object.
  338.    lastThat         Inherited from Object.
  339.  
  340.  
  341.                                                                      9
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.                             Chapter 2
  352.  
  353.                         Container Classes
  354.  
  355.  
  356. The  classes  in  the class Object hierarchy are divided into two
  357. logical  sets:  those  classes  which  contain  objects  of other
  358. classes and those classes which do  not.  We call the first set a
  359. Container class.  An  Array  class,  for  instance,  maintains an
  360. ordering on a  collection  of  objects.  Thus an Array class is a
  361. derivation of a Container class.
  362.  
  363. This chapter describes the  Container  class  and  a group of its
  364. derivatives,  known  collectively  as  the sequence grouping. The
  365. remainder of the derivatives of the Container class are discussed
  366. in the chapter entitled "Collection Hierarchy."
  367.  
  368.  
  369. 2.1  Object Ownership
  370.  
  371.  
  372. Before  we  introduce  you  to  the  class  Container,  you  must
  373. understand  the  concept  of object ownership. As in real life, a
  374. container in C++ starts out empty and must be filled with objects
  375. before  the  objects  can be said to be in the container.  Unlike
  376. the  real  world,  however,  once  objects  are  placed into  the
  377. container, they are owned by the container. This is true of class
  378. library containers. If this  were  not the case, you could add an
  379. object to  a container, then destroy the object yourself, without
  380. the container knowing it had been destroyed. This would leave the
  381. container in a very confused state.
  382.  
  383. When  the container owns an object, you  must  not  destroy  that
  384. object without first removing that object from the container. Or,
  385. you can ask  the  container  to  destroy the object for you. This
  386. restriction is based  on  the scoping rules and memory allocation
  387. in C++.
  388.  
  389. If you declare an  automatic  object (that is, an object which is
  390. local  to  your  routine), and place  that  object  in  a  global
  391. container, your local  object  will be destroyed when the routine
  392. leaves the scope in  which  it was declared. To prevent this, you
  393. must  only add heap objects (objects that  aren't  local  to  the
  394. current scope)  to  containers.  Similarly,  when  you  remove an
  395. object  from  a  global  container,  you own that object and  are
  396. responsible for destroying it and freeing the space  in  which it
  397. resides.
  398.  
  399.  
  400.                                                                     10
  401.  
  402.  
  403.  
  404. 2.2  Class Container
  405.  
  406.  
  407. The  Container  class  is an abstract class  derived  from  class
  408. Object. The class Container does the following:
  409.  
  410.    1.  It includes all classes which  can  contain  zero  or more
  411.        instances of other objects.
  412.  
  413.    2.  It provides  a method of determining whether there are any
  414.        objects present in the container and, if so,  a  method of
  415.        iterating through the objects which are present.
  416.  
  417.    3.  It defines  a method for displaying the objects present in
  418.        the container in a formatted way.
  419.  
  420. Derived from: Object
  421.  
  422. Public member functions:
  423.    printOn
  424.    isEqual
  425.    isEmpty
  426.    initIterator
  427.    forEach
  428.    firstThat
  429.    lastThat
  430.    printHeader
  431.    printSeparator
  432.    printTrailer
  433.    getItemsInContainer
  434.    isA                  Inherited from Object
  435.    nameOf               Inherited from Object
  436.    hashValue            Inherited from Object
  437.    isSortable           Inherited from Object.
  438.    isAssociation        Inherited from Object.
  439.    operator new         Inherited from Object.
  440.  
  441. 2.2.1  Function Prototype for Arguments to forEach
  442.  
  443. The  function  passed  to  the  member function forEach  has  the
  444. following prototype.
  445.  
  446.    void( *iterFuncType )( Object&, void *parameterList );
  447.  
  448. This  allows  a  parameter list to  be  passed  to  the  iterator
  449. function. The  parameter list may be null. Each iterator function
  450. must provide the means  of  parsing  the  parameter list into the
  451. parameters required by that function.
  452.  
  453. 2.2.2  Function Prototype for Arguments to firstThat
  454.  
  455. The  function  passed  to  the  member  functions  firstThat  and
  456. lastThat has the following prototype.
  457.  
  458.  
  459.                                                                     11
  460.  
  461.  
  462.  
  463.      int( *condFuncType )( Object&, void *parameterList );
  464.  
  465. This  prototype defines a function which will  return  1  if  the
  466. given object satisfies a condition.  The function  must  return 0
  467. otherwise.
  468.  
  469.  
  470. 2.3  Sequence Grouping
  471.  
  472.  
  473. The classes Stack, Queue, and  Deque  are  collectively  known as
  474. sequences.  A sequence defines a group  of  objects  that  follow
  475. these rules:
  476.  
  477.    1.  Objects can be inserted and removed.
  478.  
  479.    2.  The order of insertions and deletions is significant.
  480.  
  481.    3.  Insertions and deletions occur at the appropriate point or
  482.        points, as defined by the individual class.
  483.  
  484. Sequences provide a mechanism for determining  whether  there are
  485. any  members  of  the  group.  This  is  done with  the  function
  486. isEmpty().
  487.  
  488. The sequence grouping is not a class itself  because  the classes
  489. which make  up  the  grouping  do  not  share enough in common to
  490. warrant a separate base class. However, you may  find  it helpful
  491. to  consider  the  classes  together  when  reviewing  the object
  492. hierarchy.
  493.  
  494. 2.3.1  Class Stack
  495.  
  496. Class  Stack  is  a member of the sequence grouping of Container-
  497. derived classes. The class provides the  usual  stack operations,
  498. such as isEmpty(), push(),  and  pop().  In addition, class Stack
  499. provides a method for referencing and changing the top element of
  500. the  stack  without  popping the stack. This method, top(), is an
  501. exception to the container ownership rule, in that  it  returns a
  502. reference  to  an  object  which  is  still  owned by  the  stack
  503. container.  You must be careful not  to  destroy  the  referenced
  504. object, as this  will  disrupt the internal mechanism for storing
  505. the stack.
  506.  
  507. Derived from: Container
  508.  
  509. Public member functions:
  510.    isA
  511.    nameOf
  512.    hashValue
  513.    push
  514.    pop
  515.    top
  516.    isEmpty
  517.  
  518.  
  519.                                                                     12
  520.  
  521.  
  522.  
  523.    initIterator
  524.    printOn              Inherited from Container.
  525.    isEqual              Inherited from Container.
  526.    forEach              Inherited from Container.
  527.    firstThat            Inherited from Container.
  528.    lastThat             Inherited from Container.
  529.    printHeader          Inherited from Container.
  530.    printSeparator       Inherited from Container.
  531.    printTrailer         Inherited from Container.
  532.    getItemsInContainer  Inherited from Container.
  533.    isSortable           Inherited from Object.
  534.    isAssociation        Inherited from Object.
  535.    operator new         Inherited from Object.
  536.  
  537. 2.3.2  Class Queue
  538.  
  539. Class Queue implements  a  FIFO  container  and  associated queue
  540. methods.  Objects  are  inserted at the left and removed from the
  541. right.  You can use the member function  peek()  to  examine  the
  542. object which will be  removed  next.  Note  that peek() returns a
  543. reference  to  an  object which is  still  owned  by  the  queue;
  544. therefore  you  must  be careful not to  destroy  the  referenced
  545. object. For  a discussion of container ownership, see the section
  546. entitled "Object Ownership" at the beginning of this chapter.
  547.  
  548. Derived from: Container
  549.  
  550. Public member functions:
  551.    isA
  552.    nameOf
  553.    hashValue
  554.    peekLeft
  555.    peekRight
  556.    get
  557.    put
  558.    initIterator
  559.    printOn              Inherited from Container.
  560.    isEqual              Inherited from Container.
  561.    isEmpty              Inherited from Container.
  562.    forEach              Inherited from Container.
  563.    firstThat            Inherited from Container.
  564.    lastThat             Inherited from Container.
  565.    printHeader          Inherited from Container.
  566.    printSeparator       Inherited from Container.
  567.    printTrailer         Inherited from Container.
  568.    getItemsInContainer  Inherited from Container.
  569.    isSortable           Inherited from Object.
  570.    isAssociation        Inherited from Object.
  571.    operator new         Inherited from Object.
  572.  
  573. 2.3.3  Class Deque
  574.  
  575. Class Deque (pronounced  "deck") implements a double-ended queue.
  576. Objects  can be inserted and removed at both  the  left  and  the
  577.  
  578.  
  579.                                                                     13
  580.  
  581.  
  582.  
  583. right  ends.  You  can use the member  functions  peekLeft()  and
  584. peekRight() to examine the objects  currently at the left and the
  585. right  ends.  The  same caveats apply to  the  object  references
  586. returned  from these functions as to the  returns  of  peek()  in
  587. class  Queue  and top() in class Stack.  That  is,  you  must  be
  588. careful  not to destroy the object  referenced  by  the  returned
  589. value.  See  the  section  entitled  "Object  Ownership"  at  the
  590. beginning of the chapter for a discussion of this restriction.
  591.  
  592. Derived from: Container
  593.  
  594. Public member functions:
  595.    isA
  596.    nameOf
  597.    hashValue
  598.    peekLeft
  599.    peekRight
  600.    getLeft
  601.    getRight
  602.    putLeft
  603.    putRight
  604.    initIterator
  605.    printOn              Inherited from Container.
  606.    isEqual              Inherited from Container.
  607.    isEmpty              Inherited from Container.
  608.    forEach              Inherited from Container.
  609.    firstThat            Inherited from Container.
  610.    lastThat             Inherited from Container.
  611.    printHeader          Inherited from Container.
  612.    printSeparator       Inherited from Container.
  613.    printTrailer         Inherited from Container.
  614.    getItemsInContainer  Inherited from Container.
  615.    isSortable           Inherited from Object.
  616.    isAssociation        Inherited from Object.
  617.    operator new         Inherited from Object.
  618.  
  619.  
  620.                                                                     14
  621.  
  622.  
  623.                                                                     15
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.                             Chapter 3
  634.  
  635.                       Collection Hierarchy
  636.  
  637.  
  638. This chapter introduces the  abstract  class  Collection  and its
  639. derived classes.
  640.  
  641.  
  642. 3.1  Class Collection
  643.  
  644.  
  645. Derived classes  of the abstract class Collection are the classes
  646. you'll be using the most. For instance, since collections provide
  647. a way of gathering objects  together and operating upon them, you
  648. could start by designing a  particular section of a project using
  649. the abilities  provided by a Collection class. Later, when you've
  650. learned more about  the  characteristics of the design, you could
  651. decide upon the specific implementation of  Collection  class you
  652. desired.
  653.  
  654. The  Collection  class  provides the ability to  use  objects  of
  655. different  derived  classes,  such  as  Arrays,  Sets,  and Bags,
  656. interchangeably, as long as the functions are restricted to those
  657. available for  a Collection. A Collection is distinguished from a
  658. class  in  the  sequence  grouping  by the ability  to  determine
  659. whether an object is a member of the Collection.
  660.  
  661. Derived from: public Container
  662.  
  663. Public member functions:
  664.    add
  665.    destroy
  666.    detach
  667.    hasMember
  668.    findMember
  669.    initIterator         Inherited from Container.
  670.    isA                  Inherited from Container.
  671.    nameOf               Inherited from Container.
  672.    hashValue            Inherited from Container.
  673.    printOn              Inherited from Container.
  674.    isEqual              Inherited from Container.
  675.    isEmpty              Inherited from Container.
  676.    forEach              Inherited from Container.
  677.    firstThat            Inherited from Container.
  678.    lastThat             Inherited from Container.
  679.    printHeader          Inherited from Container.
  680.    printSeparator       Inherited from Container.
  681.  
  682.  
  683.                                                                     16
  684.  
  685.  
  686.  
  687.    printTrailer         Inherited from Container.
  688.    getItemsInContainer  Inherited from Container.
  689.    isSortable           Inherited from Object.
  690.    isAssociation        Inherited from Object.
  691.    operator new         Inherited from Object.
  692.  
  693.  
  694. 3.2  Derived Classes of Collection
  695.  
  696.  
  697. The classes derived from the class Collection are:
  698.  
  699.    HashTable
  700.       Bag
  701.          Set
  702.             Dictionary
  703.    List
  704.    DoubleList
  705.    AbstractArray
  706.      Array
  707.      SortedArray
  708.  
  709. 3.2.1  Unordered Collections
  710.  
  711. An unordered collection is a  class  derived  from  Collection in
  712. which  the  ordering  of  the  objects  in  the   class   is  not
  713. discernible.  Since the unordered collection class requires  only
  714. that  an  object  can be tested for membership in the collection,
  715. objects of any class derived  from the abstract base class Object
  716. can be put into an unordered collection.
  717.  
  718. 3.2.1.1  Class HashTable
  719.  
  720. The class HashTable provides an implementation of a collection in
  721. which  there  is  no  provision  for ordering of objects.   Class
  722. HashTable serves as a base class for the classes  Bag,  Set,  and
  723. Dictionary, which  are  all  unordered  collections  of  objects.
  724. Class HashTable was chosen as a base class because  each  of  the
  725. classes derived from this class are  implemented  using HashTable
  726. access methods.  You may notice that a derivation  of  this  sort
  727. differs  from the conceptual derivation in  other  areas  of  the
  728. hierarchy.  The difference exists  because you may find it easier
  729. to understand the  relationship  if that relationship is based on
  730. the implementation of the classes.
  731.  
  732. Derived from: Collection
  733.  
  734. Public member functions:
  735.    isA
  736.    nameOf
  737.    hashValue
  738.    add
  739.    destroy
  740.    detach
  741.  
  742.  
  743.                                                                     17
  744.  
  745.  
  746.  
  747.    hasMember
  748.    findMember
  749.    initIterator
  750.    printOn              Inherited from Container.
  751.    isEqual              Inherited from Container.
  752.    isEmpty              Inherited from Container.
  753.    forEach              Inherited from Container.
  754.    firstThat            Inherited from Container.
  755.    lastThat             Inherited from Container.
  756.    printHeader          Inherited from Container.
  757.    printSeparator       Inherited from Container.
  758.    printTrailer         Inherited from Container.
  759.    getItemsInContainer  Inherited from Container.
  760.    isSortable           Inherited from Object.
  761.    isAssociation        Inherited from Object.
  762.    operator new         Inherited from Object.
  763.  
  764. 3.2.1.2  Class Bag
  765.  
  766. The class Bag defines a  collection of objects which is identical
  767. to a HashTable. A Bag is a collection that may contain  more than
  768. one  of  the  same object. This  is  also  permissible  within  a
  769. HashTable.  We provide class Bag as a renamed  version  of  class
  770. HashTable.  You may  choose  which  class  name better suits your
  771. application.
  772.  
  773. Derived from: HashTable
  774.  
  775. Public member functions:
  776.    isA
  777.    nameOf
  778.    hashValue
  779.    add                  Inherited from HashTable.
  780.    destroy              Inherited from HashTable.
  781.    detach               Inherited from HashTable.
  782.    hasMember            Inherited from HashTable.
  783.    findMember           Inherited from HashTable.
  784.    initIterator         Inherited from HashTable.
  785.    printOn              Inherited from Container.
  786.    isEqual              Inherited from Container.
  787.    isEmpty              Inherited from Container.
  788.    forEach              Inherited from Container.
  789.    firstThat            Inherited from Container.
  790.    lastThat             Inherited from Container.
  791.    printHeader          Inherited from Container.
  792.    printSeparator       Inherited from Container.
  793.    printTrailer         Inherited from Container.
  794.    getItemsInContainer  Inherited from Container.
  795.    isSortable           Inherited from Object.
  796.    isAssociation        Inherited from Object.
  797.    operator new         Inherited from Object.
  798.  
  799.  
  800.                                                                     18
  801.  
  802.  
  803.  
  804. 3.2.1.3  Class Set
  805.  
  806. The  class Set is derived from the class  Bag.  A  Set  restricts
  807. membership  of objects in a collection to  one  of  each  object.
  808. Other than a difference in the method for adding a member,  a Set
  809. and a Bag are identical.
  810.  
  811. Derived from: Bag
  812.  
  813. Public member functions:
  814.    isA
  815.    nameOf
  816.    hashValue
  817.    add
  818.    destroy              Inherited from HashTable.
  819.    detach               Inherited from HashTable.
  820.    hasMember            Inherited from HashTable.
  821.    findMember           Inherited from HashTable.
  822.    initIterator         Inherited from HashTable.
  823.    printOn              Inherited from Container.
  824.    isEqual              Inherited from Container.
  825.    isEmpty              Inherited from Container.
  826.    forEach              Inherited from Container.
  827.    firstThat            Inherited from Container.
  828.    lastThat             Inherited from Container.
  829.    printHeader          Inherited from Container.
  830.    printSeparator       Inherited from Container.
  831.    printTrailer         Inherited from Container.
  832.    getItemsInContainer  Inherited from Container.
  833.    isSortable           Inherited from Object.
  834.    isAssociation        Inherited from Object.
  835.    operator new         Inherited from Object.
  836.  
  837. 3.2.1.4  Class Dictionary
  838.  
  839. A  dictionary is an unordered collection  of  objects  which  are
  840. derived  from  the  class  Association.    The  class  Dictionary
  841. inherits all of the properties of its parent class, Set, and adds
  842. a  lookup function.  This function allows  you  to  retrieve  the
  843. value portion of an association stored in the  dictionary  if you
  844. supply the key.
  845.  
  846. Derived from: Set
  847.  
  848. Public member functions:
  849.    isA
  850.    nameOf
  851.    hashValue
  852.    lookup
  853.    add                  Inherited from HashTable.
  854.    destroy              Inherited from HashTable.
  855.    detach               Inherited from HashTable.
  856.    hasMember            Inherited from HashTable.
  857.    findMember           Inherited from HashTable.
  858.  
  859.  
  860.                                                                     19
  861.  
  862.  
  863.  
  864.    initIterator         Inherited from HashTable.
  865.    printOn              Inherited from Container.
  866.    isEqual              Inherited from Container.
  867.    isEmpty              Inherited from Container.
  868.    forEach              Inherited from Container.
  869.    firstThat            Inherited from Container.
  870.    lastThat             Inherited from Container.
  871.    printHeader          Inherited from Container.
  872.    printSeparator       Inherited from Container.
  873.    printTrailer         Inherited from Container.
  874.    getItemsInContainer  Inherited from Container.
  875.    isSortable           Inherited from Object.
  876.    isAssociation        Inherited from Object.
  877.    operator new         Inherited from Object.
  878.  
  879. 3.2.1.5  Class List
  880.  
  881. The  class List provides an implementation  of  a  collection  in
  882. which objects are linked together to form a chain. Objects can be
  883. added and removed only at the head of the chain. You can traverse
  884. the list to examine the objects. The traversal starts at the head
  885. and continues until no more objects are found in the list.
  886.  
  887. Derived from: Collection
  888.  
  889. Public member functions:
  890.    isA
  891.    nameOf
  892.    hashValue
  893.    peekHead
  894.    add
  895.    detach
  896.    initIterator
  897.    destroy              Inherited from Collection.
  898.    hasMember            Inherited from Collection.
  899.    findMember           Inherited from Collection.
  900.    printOn              Inherited from Container.
  901.    isEqual              Inherited from Container.
  902.    isEmpty              Inherited from Container.
  903.    forEach              Inherited from Container.
  904.    firstThat            Inherited from Container.
  905.    lastThat             Inherited from Container.
  906.    printHeader          Inherited from Container.
  907.    printSeparator       Inherited from Container.
  908.    printTrailer         Inherited from Container.
  909.    getItemsInContainer  Inherited from Container.
  910.    isSortable           Inherited from Object.
  911.    isAssociation        Inherited from Object.
  912.    operator new         Inherited from Object.
  913.  
  914. 3.2.1.6  Class DoubleList
  915.  
  916. The class DoubleList provides a  method of placing objects on two
  917. lists while maintaining only one object. You can  add  and remove
  918.  
  919.  
  920.                                                                     20
  921.  
  922.  
  923.  
  924. objects at  the  two  ends  of  the  lists.  Furthermore, you can
  925. traverse the list in  either  direction,  beginning at either the
  926. head or the tail, and reversing direction in the  middle  of  the
  927. iteration  process.    The  member  function  initReverseIterator
  928. begins the iteration process at the tail of the list.   To permit
  929. direction  reversal,  the  operator  --()  is  defined   for  the
  930. DoubleListIterator  class.  For a complete  list  of  the  member
  931. functions  of  the  DoubleListIterator  class,  see  the  chapter
  932. entitled "Classes In the  ContainerIterator  Hierarchy,"  on page
  933. 25.
  934.  
  935. Derived from: Collection
  936.  
  937. Public member functions:
  938.    isA
  939.    nameOf
  940.    hashValue
  941.    add
  942.    detach
  943.    detachFromHead
  944.    detachFromTail
  945.    peekAtHead
  946.    peekAtTail
  947.    addAtHead
  948.    addAtTail
  949.    destroyFromHead
  950.    destroyFromTail
  951.    initIterator
  952.    initReverseIterator
  953.    destroy              Inherited from Collection.
  954.    hasMember            Inherited from Collection.
  955.    findMember           Inherited from Collection.
  956.    printOn              Inherited from Container.
  957.    isEqual              Inherited from Container.
  958.    isEmpty              Inherited from Container.
  959.    forEach              Inherited from Container.
  960.    firstThat            Inherited from Container.
  961.    lastThat             Inherited from Container.
  962.    printHeader          Inherited from Container.
  963.    printSeparator       Inherited from Container.
  964.    printTrailer         Inherited from Container.
  965.    getItemsInContainer  Inherited from Container.
  966.    isSortable           Inherited from Object.
  967.    isAssociation        Inherited from Object.
  968.    operator new         Inherited from Object.
  969.  
  970. 3.2.2  Ordered Collections
  971.  
  972. This section  describes the group of classes which called ordered
  973. collections. A class which is  an ordered collection must be made
  974. up of objects for  which  there  are ordering operations defined;
  975. that is, they must be derived from class Sortable.
  976.  
  977.  
  978.                                                                     21
  979.  
  980.  
  981.  
  982. 3.2.2.1  Class AbstractArray
  983.  
  984. The class AbstractArray has random  access to the elements of the
  985. collection. For an object to be an array implies that you can use
  986. an index to access the elements of that object.
  987. The  reason  that  the  AbstractArray  class exists is  that  the
  988. derived classes SortedArray and  Array  have  enough in common to
  989. warrant combining the common  properties  into  an  abstract base
  990. class for classes.  Since the derived classes differ only  in the
  991. implementation  of  the  member  function  add,  detach,  and the
  992. subscript  operator, the remaining functions can be  encapsulated
  993. in the AbstractArray base class.
  994.  
  995. Derived from: Collection
  996.  
  997. Public member functions:
  998.    isA
  999.    nameOf
  1000.    hashValue
  1001.    add
  1002.    detach
  1003.    initIterator
  1004.    lowerBound
  1005.    upperBound
  1006.    arraySize
  1007.    isEqual
  1008.    destroy              Inherited from Collection.
  1009.    hasMember            Inherited from Collection.
  1010.    findMember           Inherited from Collection.
  1011.    printOn              Inherited from Container.
  1012.    isEmpty              Inherited from Container.
  1013.    forEach              Inherited from Container.
  1014.    firstThat            Inherited from Container.
  1015.    lastThat             Inherited from Container.
  1016.    printHeader          Inherited from Container.
  1017.    printSeparator       Inherited from Container.
  1018.    printTrailer         Inherited from Container.
  1019.    getItemsInContainer  Inherited from Container.
  1020.    isSortable           Inherited from Object.
  1021.    isAssociation        Inherited from Object.
  1022.    operator new         Inherited from Object.
  1023.  
  1024. 3.2.2.2  Class Array
  1025.  
  1026. The instance  class Array is derived from class AbstractArray. An
  1027. Array object defines  an  array  in  which  the  ordering  of the
  1028. elements is undefined.  That  is,  the  element at index i of the
  1029. array has no relationship to the element at index i + 1.
  1030.  
  1031. The  Array  class  adds  the  member  function  addAt()  and  the
  1032. subscript  operator  the  its  parent class, class AbstractArray.
  1033. While the inherited member function add()  (inherited  from class
  1034. Collection) stores a given object in the first available space in
  1035. the array, the addAt() member  function store the given object at
  1036.  
  1037.  
  1038.                                                                     22
  1039.  
  1040.  
  1041.  
  1042. a specified  index.  Similarly, the subscript operator returns an
  1043. lvalue to which you may assign an object reference.
  1044.  
  1045. Derived from: AbstractArray
  1046.  
  1047. Public member functions:
  1048.    isA
  1049.    nameOf
  1050.    hashValue
  1051.    addAt
  1052.    operator []
  1053.    add
  1054.    detach
  1055.    initIterator         Inherited from AbstractArray
  1056.    lowerBound           Inherited from AbstractArray
  1057.    upperBound           Inherited from AbstractArray
  1058.    arraySize            Inherited from AbstractArray
  1059.    isEqual              Inherited from AbstractArray
  1060.    destroy              Inherited from Collection.
  1061.    hasMember            Inherited from Collection.
  1062.    findMember           Inherited from Collection.
  1063.    printOn              Inherited from Container.
  1064.    isEmpty              Inherited from Container.
  1065.    forEach              Inherited from Container.
  1066.    firstThat            Inherited from Container.
  1067.    lastThat             Inherited from Container.
  1068.    printHeader          Inherited from Container.
  1069.    printSeparator       Inherited from Container.
  1070.    printTrailer         Inherited from Container.
  1071.    getItemsInContainer  Inherited from Container.
  1072.    isSortable           Inherited from Object.
  1073.    isAssociation        Inherited from Object.
  1074.    operator new         Inherited from Object.
  1075.  
  1076. 3.2.2.3  Class SortedArray
  1077.  
  1078. The class SortedArray defines an array in which the objects which
  1079. make up the  array  are  sorted  in ascending order. That is, the
  1080. object at index n is less  than  or  equal to the object at index
  1081. n+1. Note that the  operator  < must be defined for comparing any
  1082. objects in the array.
  1083.  
  1084. The differences between the  class  Array  and  class SortedArray
  1085. are:
  1086.  
  1087.    1.  The method for adding an object at a given index, addAt(),
  1088.        which is provided by class Array, is not provided in class
  1089.        SortedArray.
  1090.  
  1091.    2.  Unlike the subscript operator  for  the  class  Array, the
  1092.        subscript operator in class SortedArray, operator [], does
  1093.        not  return  an  lvalue.  This  restriction  prevents  any
  1094.        additions to the array  which  my  disrupt the ordering of
  1095.        objects in the array.
  1096.  
  1097.  
  1098.                                                                     23
  1099.  
  1100.  
  1101.  
  1102. Derived from: AbstractArray
  1103.  
  1104. Public member functions:
  1105.    isA
  1106.    nameOf
  1107.    hashValue
  1108.    operator []
  1109.    add
  1110.    detach
  1111.    initIterator         Inherited from AbstractArray
  1112.    lowerBound           Inherited from AbstractArray
  1113.    upperBound           Inherited from AbstractArray
  1114.    arraySize            Inherited from AbstractArray
  1115.    isEqual              Inherited from AbstractArray
  1116.    destroy              Inherited from Collection.
  1117.    hasMember            Inherited from Collection.
  1118.    findMember           Inherited from Collection.
  1119.    printOn              Inherited from Container.
  1120.    isEmpty              Inherited from Container.
  1121.    forEach              Inherited from Container.
  1122.    firstThat            Inherited from Container.
  1123.    lastThat             Inherited from Container.
  1124.    printHeader          Inherited from Container.
  1125.    printSeparator       Inherited from Container.
  1126.    printTrailer         Inherited from Container.
  1127.    getItemsInContainer  Inherited from Container.
  1128.    isSortable           Inherited from Object.
  1129.    isAssociation        Inherited from Object.
  1130.    operator new         Inherited from Object.
  1131.  
  1132.  
  1133.                                                                     24
  1134.  
  1135.  
  1136.                                                                     25
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.                             Chapter 4
  1147.  
  1148.            Classes in the ContainerIterator Hierarchy
  1149.  
  1150.  
  1151. Each class in the class  Object-based hierarchy must have a means
  1152. of iterating  through any sub-objects contained in the class. The
  1153. ContainerIterator-based hierarchy fulfills this requirement.  The
  1154. abstract  base  class of this  hierarchy,  ContainerIterator,  is
  1155. declared  as a friend of the abstract  base  class  Object.  This
  1156. relationship means that  you  can apply iterators to every object
  1157. in  the  class  Object  hierarchy  without  having  to  know  the
  1158. derivation of the object which you are iterating.
  1159.  
  1160. Iterators  occur  frequently  in  programs  written   in   C.  To
  1161. illustrate  this  situation,  we  give  an example of the use  of
  1162. iterators in C and translate that example to C++. The following C
  1163. code fragment uses an iterator to step through the elements of an
  1164. array of strings.
  1165.  
  1166.    char *text[] = { "this", "is", "some", "text", 0 };
  1167.    char **cur = text;
  1168.  
  1169.    while ( *cur != 0 )
  1170.    {
  1171.       . . .
  1172.       cur++;
  1173.    }
  1174.  
  1175. The steps of the iterations are:
  1176.  
  1177.    1.  Initialize the iterator. This  occurs  in  the declaration
  1178.        and initialization statement which begins 'cur *text[] = {
  1179.        . . . .'
  1180.  
  1181.    2.  Test the iterator for completion of the iterating process.
  1182.        This occurs in the  conditional  of  the  while statement,
  1183.        'while ( *cur != 0 ).'
  1184.  
  1185.    3.  Increment the iterator.  This  is  done  by  the statement
  1186.        'cur++.'
  1187.  
  1188. We  extend this form in C++. The above  example  can  be  written
  1189. using an instantiation of an iterator class as follows.
  1190.  
  1191.    Array myArray( . . . );
  1192.    ContainerIterator myIterator = myArray.initIterator();
  1193.  
  1194.  
  1195.                                                                     26
  1196.  
  1197.  
  1198.  
  1199.    while ( myIterator != 0 )
  1200.    {
  1201.       . . .
  1202.       myIterator++;
  1203.    }
  1204.  
  1205. To be an iterator, therefore, a class must do the following:
  1206.  
  1207.    1.  Overload   the   preincrement   operator,  operator  ++().
  1208.        Operator ++() should return a reference to the next object
  1209.        in the iteration sequence.
  1210.  
  1211.    2.  Provide an operator which  converts  the  iterator  to the
  1212.        predefined type int.    This  conversion  is  necessary to
  1213.        inform  users  of  the  iterator  that there are  no  more
  1214.        objects left in the iteration sequence.
  1215.  
  1216.    3.  Provide a function to restart the iteration process at any
  1217.        time after a program creates the iterator.
  1218.  
  1219. The iterators available in  the  class  library are listed below,
  1220. along  with  their  member functions.   You  may  note  that  the
  1221. DoubleListIterator  class  defines  the  predecrement   operator,
  1222. operator --(), in addition to the other required functions.  This
  1223. operator appears in class DoubleListIterator since it is possible
  1224. to traverse a DoubleList in either direction.
  1225.  
  1226. Class ContainerIterator:
  1227.  
  1228. Public member functions:
  1229.    operator ++
  1230.    operator int
  1231.    restart
  1232.  
  1233.  
  1234. Class ArrayIterator, derived from ContainerIterator
  1235.  
  1236. Public member functions:
  1237.    operator ++
  1238.    operator int
  1239.    restart
  1240.  
  1241.  
  1242. Class DoubleListIterator, derived from ContainerIterator
  1243.  
  1244. Public member functions:
  1245.    operator ++
  1246.    operator --
  1247.    operator int
  1248.    restart
  1249.  
  1250.  
  1251. Class ListIterator, derived from ContainerIterator
  1252.  
  1253.  
  1254.                                                                     27
  1255.  
  1256.  
  1257.  
  1258. Public member functions:
  1259.    operator ++
  1260.    operator int
  1261.    restart
  1262.  
  1263.  
  1264.                                                                     28
  1265.  
  1266.  
  1267.                                                                     29
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.                             Chapter 5
  1278.  
  1279.                 Class Library Directory Stucture
  1280.  
  1281.  
  1282. When you load Turbo C++ on to your disk, the  files  in the class
  1283. library are set up in the following directory structure:
  1284.  
  1285.                          CLASSLIB\
  1286.                             |
  1287.     +-----------+-----------+------------+------------+
  1288.     |           |           |            |            |
  1289.  INCLUDE\    SOURCE\   CLASSLIB.DOC     LIB\      EXAMPLES\
  1290.  
  1291. The  CLASSLIB  directory  itself is a subdirectory of the TC root
  1292. directory.  This will usually be directory \TC, if you have taken
  1293. the default options when installing Turbo C++.   The  contents of
  1294. the directories in the class library are discussed in more detail
  1295. in the following sections.
  1296.  
  1297.  
  1298. 5.1  Directory INCLUDE
  1299.  
  1300.  
  1301. The directory INCLUDE  contains  the  header  files  necessary to
  1302. compile a program  which  uses  the  class library.  You must put
  1303. this directory on the include search path when  you  compile your
  1304. program.
  1305.  
  1306.  
  1307. 5.2  Directory SOURCE
  1308.  
  1309.  
  1310. The directory SOURCE contains the  source  files  which implement
  1311. many  of  the  member  functions  of the classes in the  library.
  1312. These source files are provided as a guide  for  implementing new
  1313. classes.
  1314.  
  1315. You also need these source files  if  you want to build a library
  1316. in a different memory model than the one provided on  the release
  1317. diskette.    The  supplied batch file BUILD.BAT  builds  a  class
  1318. library of the specified memory  model and places that library in
  1319. the LIB directory.    To  build  a library using the large memory
  1320. model, type BUILD L in the  SOURCE  directory.  When you do this,
  1321. the batch file will invoke the Turbo C++ compiler  to  build  all
  1322. the files  in  the  class  library  using  large model.  Then the
  1323. library file archiver, TLIB, will create a library TCLASSL.LIB in
  1324. the LIB subdirectory of the CLASSLIB directory.
  1325.  
  1326.  
  1327.                                                                     30
  1328.  
  1329.  
  1330.  
  1331. An important note:  When you  use  a library which you have built
  1332. in one of the sample projects, you must change the  library which
  1333. is included in your project to be the one which  you  built.  You
  1334. must also be sure to compile your project with precisely the same
  1335. switches and options with which you built the library.  If you do
  1336. not have the same options, you will get warnings from  the linker
  1337. when the .EXE file is built.
  1338.  
  1339.  
  1340. 5.3  Directory LIB
  1341.  
  1342.  
  1343. The directory LIB contains the compiled  source  modules archived
  1344. into a  library.    You  must  put  this directory on the library
  1345. search path when you  link  your program.  If you build different
  1346. memory  models  of  the class library, you will put the resulting
  1347. libraries in this directory.
  1348.  
  1349.  
  1350. 5.4  Directory EXAMPLES
  1351.  
  1352.  
  1353. The directory EXAMPLES contains the  example  programs  and their
  1354. project files.   You  may  compile  these programs to see how the
  1355. parts  of  the  class  library  may  be  put  together to form an
  1356. application.  Most of the example  use  one or two of the classes
  1357. in the hierarchy.  Other examples are more complex.   The example
  1358. programs, and the classes which they use, are listed below.
  1359.  
  1360.    1.  STRNGMAX:  A very simple example which uses class String.
  1361.  
  1362.    2.  REVERSE:  An intermediate example which  uses  class Stack
  1363.        and class String.
  1364.  
  1365.    3.  LOOKUP:     An  intermediate  example  which  uses   class
  1366.        Dictionary and class Association.
  1367.  
  1368.    4.  QUEUETST:  An intermediate example which uses  class Queue
  1369.        and introduces a non-hierarchical class, class Time.
  1370.  
  1371.    5.  DIRECTRY:   An advanced example which illustrates  derived
  1372.        user classes and uses class SortedArray.
  1373.  
  1374.  
  1375.                                                                     31
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.                             Chapter 6
  1386.  
  1387.                Conventions Used In Class Libraries
  1388.  
  1389.  
  1390. To provide a consistent interface to the code in  the  C++  class
  1391. libraries, we have adopted the following conventions.  We suggest
  1392. that  you  also  follow  these  conventions, so as to reduce  the
  1393. possibility of name conflicts and other problems.
  1394.  
  1395.  
  1396. 6.1  File Naming
  1397.  
  1398.  
  1399. Files which  contain class definitions are named after the class,
  1400. with some alterations necessary due to the MS-DOS eight-character
  1401. file  name  limit.  The  file  SET.H,  therefore,   contains  the
  1402. definition for the  class  Set.  Additionally,  the  file SET.CPP
  1403. contains the implementation of  member  functions  for  the class
  1404. Set. If no member functions are needed, the .CPP file for a class
  1405. is omitted.
  1406.  
  1407. Header files contain  preprocessor directives to prevent multiple
  1408. inclusion.  Each  header  file  tests  for   the   definition  of
  1409. __<filename>_H, and if this  symbol is not defined, defines it.
  1410.  
  1411.  
  1412. 6.2  Source Naming
  1413.  
  1414.  
  1415. Class  names  in  the library begin with  an  upper-case  letter.
  1416. Likewise, each word within a class name begins with an upper-case
  1417. letter (for example, class  DoubleList).  Member  functions  of a
  1418. class begin with a  lower-case  letter,  but any subsequent words
  1419. begin with upper-case letters (for example, printOn).
  1420.  
  1421. Names of the private parts of  a  class are made up of lower-case
  1422. letters only. Class  member  functions  and  parameter  names are
  1423. chosen based on their ability to convey their meaning efficiently
  1424. and  correctly.  For  example, unless it is desirable to hide the
  1425. fact  that  a  data item is a pointer, all pointer names end with
  1426. Ptr, such as aPtr.
  1427.  
  1428. Types names in  the  class library also follow these conventions.
  1429. All type names follow the rules for member function names and end
  1430. with the word Type; for example, hashValueType. Pointer types end
  1431. with PtrType.
  1432.  
  1433.  
  1434.                                                                     32
  1435.  
  1436.  
  1437.  
  1438. 6.3  Commenting Style
  1439.  
  1440.  
  1441. If you have looked at the source code for  the  class  libraries,
  1442. you may have noticed that the style used to comment the  files is
  1443. different from the style with which you are  familiar.   Although
  1444. the  style  may  seem  confusing  at first, it has an  underlying
  1445. structure and organization which makes the job of documenting and
  1446. maintaining of  large programs easier.  In addition, the comments
  1447. help  the  reader  who is unfamiliar with the capabilities of the
  1448. library make sense of the overwhelming amount of code available.
  1449.  
  1450. The following paragraphs outline the  structure  of  each  of the
  1451. major divisions which make up a source file.  You  are encouraged
  1452. to  examine  the  source  code  to learn how these divisions  fit
  1453. together in a source file.
  1454.  
  1455. 6.3.1  Module Header
  1456.  
  1457. Each  file,  or  module, in the class library contains an initial
  1458. header which comes  immediately  after the copyright notice.  The
  1459. format of this module header is:
  1460.  
  1461. // Module //
  1462.  
  1463. // Contents ------------------------------------------------
  1464. //
  1465. //   The functions, variables, classes, types, etc. which
  1466. //   make up this module are listed here.
  1467. //
  1468. // Description
  1469. //
  1470. //   A brief description of what the module contains and how
  1471. //   it relates to the other classes in the library is
  1472. //   given here.
  1473. //
  1474. // End -----------------------------------------------------
  1475.  
  1476. 6.3.2  Dependencies
  1477.  
  1478. An  important  part of any C or C++ source file is  the  list  of
  1479. files which are included as part of this source file.  The source
  1480. file is then said to depend upon those files.    This  dependency
  1481. occurs  in  two  cases.  In the first, a function or class within
  1482. the file may include in its prototype a type which is  defined in
  1483. another file.  This dependency is called an interface dependency,
  1484. since it  affects the prototype, or interface, information of the
  1485. source file.  Dependencies of this type are put in  the interface
  1486. dependency division, which is formatted as:
  1487.  
  1488. // Interface Dependencies ----------------------------------
  1489.  
  1490. #includes go here, or // None if there are no interface
  1491. dependencies.
  1492.  
  1493.  
  1494.                                                                     33
  1495.  
  1496.  
  1497.  
  1498. // End Interface Dependencies ------------------------------
  1499.  
  1500. The  second  case  of dependency is  when  the  statements  of  a
  1501. function require a definition which is in another  file,  such as
  1502. the declaration of a local variable of a type which is defined in
  1503. stdlib.h.   These  dependencies  are  put  in  the implementation
  1504. dependency region, which has the following format.
  1505.  
  1506. // Implementation Dependencies -----------------------------
  1507.  
  1508. #includes go here, or // None if there are no implementation
  1509. dependencies.
  1510.  
  1511. // End Implementation Dependencies -------------------------
  1512.  
  1513. 6.3.3  Type Header
  1514.  
  1515. Each type, class,  and  structure  definition  has  an associated
  1516. header which comes  after  the definition.  This header describes
  1517. the  item and how it might be used and defines the members of the
  1518. structure or class.  The class header has the following format:
  1519.  
  1520. // Class // (or Type, Structure)
  1521.  
  1522. class definition goes here
  1523.  
  1524. // Description ---------------------------------------------
  1525. //
  1526. //        A brief description of the item and how to use it.
  1527. //
  1528. // Members of the class or structure are listed here.
  1529. //
  1530. // End -----------------------------------------------------
  1531.  
  1532. 6.3.4  Function Header
  1533.  
  1534. Each  function,  constructor,  destructor,  member  function,  or
  1535. friend has a  header  which  comes  after  the  prototype  of the
  1536. function  and  before  the  implementation  body.     The  header
  1537. summarizes the function, lists and  describes  the  parameters to
  1538. the function, describes the return value, describes  the internal
  1539. workings of the  function,  and lists remarks about side effects,
  1540. assumptions, and general warnings and  cautions.  The format of a
  1541. function header is given below.
  1542.  
  1543. // Function // (or Member Function, Constructor, etc.)
  1544.  
  1545. function prototype
  1546.  
  1547. // Summary -------------------------------------------------
  1548. //
  1549. //        A brief summary of the function.
  1550. //
  1551. // Parameters
  1552.  
  1553.  
  1554.                                                                     34
  1555.  
  1556.  
  1557.  
  1558. //
  1559. //        A description of each of the parameters to the
  1560. //        function and how they are used.
  1561. //
  1562. // Return Value
  1563. //
  1564. //        A description of the value returned to the
  1565. //        function's caller.
  1566. //
  1567. // Functional Description
  1568. //
  1569. //        A description of the overall flow and operation
  1570. //        of the function.
  1571. //
  1572. // Remarks
  1573. //
  1574. //        A list of side effects, assumptions, warnings,
  1575. //        and cautions.
  1576. //
  1577. // End -----------------------------------------------------
  1578.  
  1579. 6.3.5  Body Comments
  1580.  
  1581. Comments which occur within the body of a function are called
  1582. body comments.  Body comments guide the reader through the
  1583. details of the implementation of a function.  A body comment has
  1584. the following form:
  1585.  
  1586. // Body Comment
  1587. //
  1588. //        Comment goes here.
  1589. //
  1590. // End
  1591.  
  1592.  
  1593.                                                                     35
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.                               Index
  1604.  
  1605.  
  1606.        .EXE linking 29             L
  1607.                                    Linker warning messages
  1608.        A                              29
  1609.        Association 6, 8, 30
  1610.                                    M
  1611.        B                           Memory Model
  1612.        Bag 17                         building libraries
  1613.        body comments 34               29
  1614.                                    module header 32
  1615.        C
  1616.        class header 33             N
  1617.        classes                     NOOBJECT 6
  1618.           abstract
  1619.              defined 5             O
  1620.        Collection 15               Object (class) 5
  1621.        commenting style 32         object-based hierarchy
  1622.        Container 9, 10                defined 5
  1623.        ContainerIterator 25        object ownership 9
  1624.                                    ordered collection 20
  1625.        D
  1626.        Deque 12                    Q
  1627.        Dictionary 30               Queue 30
  1628.        double-ended queue 12       queue 12
  1629.  
  1630.        E                           S
  1631.        Error (class) 6             sequence 11
  1632.                                    Set 18
  1633.        F                           sortable 7
  1634.        function header 33          SortedArray 30
  1635.                                    Stack 30
  1636.        H                           stack 11
  1637.        HashTable 16                String 30
  1638.        hierarchy
  1639.           object-based             T
  1640.              defined 5             theErrorObject 7
  1641.  
  1642.        I                           U
  1643.        implementation              unordered collection 16
  1644.           dependency 33
  1645.        interface dependency 32     Z
  1646.        iterator 25                 ZERO 6
  1647.