C++EAS-E PROGRAMMER'S REFERENCE MANUAL

The files in EAS-E CODE present routines that can be used by a C++ programmer to efficiently store, retrieve and find members of very large ranked sets.  We will refer to these routines, and the functionality they provide, as C++EAS-E.  To use the routines provided, copy all files, except Main.cpp, to your C++ program and recompile.  Main.cpp may be used as the main routine of a stand alone program in which you experiment with C++EAS-E commands before using them "for real."

SetDef.h and RankedSetDef.h(Public extract) contain the public attributes and procedures (a.k.a. "methods") of C++EAS-E.  The second of these files is the public part of information defined in RankedSetDef.h. The present page documents this interface.  The sequence of topics presented here deviates somewhat from that in the files, to facilitate explanation. 

The principal C++ classes with which the user's program interacts are RankedSet and Cursor.  Principal actions are to file a member into a RankedSet; remove the first, last or some specific member; use a Cursor to find (but not remove) the first or last member; find a member with ranking attribute =, ³ , or £  some value; or to advance the Cursor forward or backwards in the set.  Other user actions include the creating and destroying (construction and destruction) of a RankedSet or Cursor.  These various actions on the principal entities make use of a structure, RAandMID, various types defined in typedef statements, and terms defined in #DEFINE statements.  We first present these terms, typedefs and structure, then present the principal C++ classes, namely RankedSet and Cursor.

SUPPORTING DEFINITIONS

#define memberType long
#define RAType double
#define NULLmID -1L
#define NULLCursor NULL

Throughout these routines reference is made to memberType and RAType (ranking attribute type).  These are defined here as long and double, respectively.    To indicate a non-existent member use NULLmID.  This is defined here as -1L.  To indicate a non-existent Cursor write NULLCursor.  This is defined here as NULL.  

   typedef enum fileReturnCode {
        error = -1,
        blocked,
        filed
        };

This defined type is returned by the fileMemberIntoSet command.  In the case of RankedSets its value should always be "filed" ("blocked" may be returned when the software files into subsidiary structures not directly accessed by the user.)

   typedef enum removeReturnCode {
        RCCError = -1,
        notFound,
        removed
        };

This defined type is returned by various "remove" commands.  Its value should be either "removed" or "notFound".

   typedef enum insertLocType {
        atFront = 1,
        First = 1,
        internal = 2,
        between = 3,
        after = 3,
        atBack = 4,
        Last = 4,
        Empty = 5
        };

This defined type is mostly used by subsidiary entities and routines not available to the user.  It may, however, be used as an argument to the findFirstOrLast routine to indicate "First" or "Last".  The former is indicated by a value of "atFront" or "First"; the latter is indicated by "atBack" or "Last". Rather than the findFirstOrLast routine, the programmer is expected to usually use the findFirst or findLast routines.

   typedef enum direction {
        Forward = 0,
        Backward = 1,
        Backwards = 1
        };

This defined type is used as an argument to the findNextOrPrior routine to indicate the direction in which the Cursor is to be advanced. Rather than the findNextOrPrior routine, the programmer is expected to usually use the findNext or findPrior routines.

   typedef enum findInstruction {
       Equal = 0,
       EqualOrHigher = 1,
       EqualOrLower = 2,
       FirstHigher = 3,    
       NextHigher = 3, 
       FirstLower = 4,
       NextLower = 4
       };  

This defined type is used as an argument to the findAsInstructed routine to specify the characteristics of the sought-for member. Depending on the value of this argument the findAsInstructed behaves like the findEqual, findEqualOrHigher, etc., routines.

   typedef enum Cu_Status {
      NotInSet,
      Bound,
      Loose
      };

This defined type is returned by the CuState() routine. A value of "bound" or "loose" indicates that the Cursor is in a set.

   typedef enum DestroyInstructionNE {
       WarnIFNotEmpty,
       ErrorIFNotEmpty,
       OKtoDestroyIFNotEmpty
       };

typedef enum DestroyInstructionCC {

       ErrorIfContainsCursors
       RemoveCursorsAndWarnIfCC,
       RemoveCursorsAndDontWarnIfCC,
       DestroyWithoutRemovingCursors
       };   

Two attributes of RankedSet are of the above two defined types.  These attributes specify how the executing program should behave if the program attempts to destroy a RankedSet which still contains members or still contains Cursors.

   struct RAandMID {
       RAType RM_rankingAtt;
       memberType RM_memberID; 
         };

This structure contains the values of the ranking attribute and the memberID of an entity which typically is, was or will be in some set.  Specifically, there are "remove" and "find" routines which must return both ranking attribute and memberID. This is accomplished by means of the RAandMID structure.  

PRINCIPAL C++ CLASSES

   class RankedSet {

RankedSet is defined as a class.  For example, if machine_group owns a set called "queue" this is told to C++ EAS-E as follows:

      Class machine_group {
          public:
              RankedSet  queue;

Following are the public attributes ("properties") and routines ("methods") of this class.

       DestroyInstructionNE destroyInstructionNE;
       DestroyInstructionCC destroyInstructionCC;

These attributes of RankedSet specify how the executing program is to respond if asked to destroy a RankedSet which still contains members or Cursors.  More at the definitions of DestroyInstructionNE and DestroyInstructionCC.

RankedSet ();

RankedSet (DestroyInstructionNE diNE, DestroyInstructionCC diCC);

The second constructor specifies the initial values of the destroyInstructionNE and destroyInstructionCC attributes.  Possible values of these attributes are presented in the DestroyInstructionNE and DestroyInstructionCC typedefs.  The attributes indicate how the executing program should respond if the user attempts to destroy a set which still contains members or still contains Cursors.  The default constructor sets these attributes to ErrorIfNotEmpty and ErrorIfContainsCursors, respectively.  Remember that C++ destroys entities when a program terminates and when variables pass out of scope.  If the program is about to end it is advisable to set the warning attributes to OKtoDestroyIfNotEmpty and DestroyWithoutRemovingCursors, respectively.  This will avoid error messages upon termination of program.  If the program is to continue, but a set instance is about to pass out of scope, it is advisable to set the attributes to OKtoDestroyIfNotEmpty and RemoveCursorsAndDontWarnIfCC.  A RankedSet contains pointers to its member rather than the members themselves.  The members are not destroyed when the set is destroyed.

~RankedSet () ; 

Standard destructor. 

long NrInSet () { return nrInSet ;}

Returns the number of members currently in the set. E.g., if mgPtr points to an entity of type machine_group (which owns a set called "queue") then

                int n = mgPtr->queue.NrInSet();

returns the number of members in the queue of the specified machine group.

RAType MinRA () {return minRA;}  

Returns the value of the smallest ranking attributes in the set.   

memberType MIDofMin () {return mIDofMin;}

Returns the memberID of the member with the lowest ranking attribute. If the set is empty NULLmID is returned.  These are usually pointers.  For example, if the members of the set are jobs, perhaps ranked on job priority, then one could write :

         job * J = (job*) mgPtr-> queue. MIDofMin();

RAType MaxRA () {return maxRA;}

Returns the largest value of the ranking attribute among any member of the set.
More at MinRA.

memberType MIDofMax () {return mIDofMax;}       

Returns the memberID of the member with the largest value of the ranking attribute.  More at MIDofMin.

fileReturnCode fileMemberIntoSet (RAType RA, memberType mID);

Files a member into the set. The first argument provides the value of its ranking attribute.  The second argument provides its memberID.  It is these (RA, mID) pairs which are stored in the set. The members of the set are ordered primarily on RA and, in case of ties among RA, secondarily by mID.  Thus the "next" member, M2, after a given member, M1, is the one with the same RA as M1 and next higher mID or, if no such member exists, the M2 with the next highest value of RA.  If more than one member has this next highest value of RA then M2 is the one with the lowest mID among these.  In other words, the set is ordered "lexicographically by RA and then mID. The value of the function is of type fileReturnCode.  Its value should be "filed".  More at the fileReturnCode typedef.

RAandMID removeFirstFromSet () 

Removes the first member of the set. It returns an RAandMID with the ranking attribute and memberID of the member removed. If the set is empty then RM_memberID equals NULLmID.  More at RAandMID.

RAandMID removeLastFromSet () 

Removes the last number of the set and returns an RAandMID with the ranking attribute and memberID of the member removed.  More at removeFirstFromSet.

RAandMID removeForLFromSet (insertLocType ilt) ;

This routine acts like removeFirstFromSet or removeLastFromSet depending on the argument, ilt.  See the insertLocType typedef.

removeReturnCode removeThisFromSet (RAType RA, memberType memberID) ;
removeReturnCode removeThisFromSet (RAandMID) ;

These routines remove a specific member from the set.  The first  specifies the member by its ranking attribute and its memberID.  The second specifies the member by a RAandMID with the same information.  The value of the function indicates whether the member was found (and removed) or not found.  See the removeReturnCode typedef.

RAandMID findFirst (Cursor * cuPtr) ;

    Returns an RAandMID that contains the ranking attribute and memberID of the first member of the set.  The member is not removed from the set.  If the set is empty the returned RAandMID has RM_memberID equal NULLmID.   The routine has a pointer to a Cursor as its first argument. The Cursor may be used in a subsequent findNext or findPrior command. For example:

         Cursor Cu;
        Cursor * CuPtr = &Cu ;
        RAandMID RM;
         RM = mgPtr->queue.findFirst (CuPtr) ;

        …

        RM =CuPtr→findNext();

See the findNext method of Cursor.

If the Cursor is not in any set the findFirst places the Cursor in the set.  It is permitted to use a Cursor that is already in the specified set.  It is not permitted to use a Cursor that is in some other set.  If necessary, first use the removeThisCursorFromSet routine.  If it is not known whether the Cursor is in some set, determine this using the Cursor::CuState routine.

RAandMID findLast (Cursor * cuPtr) ;

Returns the RAandMID of the last member of the set.  The member is not removed.  More at findFirst.

RAandMID findFirstOrLast (Cursor * cuPtr, insertLocType ilt) ;

Returns an RAandMID with the ranking attribute and memberID of either the first or the last member depend on the value of ilt.  More at findFirst and the insertLocType typedef.     

RAandMID findEqual (Cursor * cuPtr, RAType ra, memberType mID) ;

Returns an RAandMID containing a set member with the specified ranking attribute RA.  If the third argument, mID, is NULLmID then findEqual returns the ranking attribute and memberID of the member that has the specified value of the ranking attribute and the lowest mID among these.  If mID is not NULLmID then findEqual returns the specific ranking attribute and memberID.  If the specified member, in the latter case, or a member with the specified ranking attribute, in the former case, cannot be found then findEqual returns a RAandMID with RM_memberID equal to NULLmID.  The first argument to findEqual is a Cursor pointer which may be used in subsequent findNext or findPrior command.  More at findFirst.

RAandMID findEqualOrHigher (Cursor * cuPtr, RAType ra, memberType mID) ;

Returns the RAandMID of a member with the same or higher ranking attribute.  If the third argument mID is NULLmID  then the memberID of the members is ignored.  The routine returns the first (lowest  ranking) member of the set which meets the specification.  If the third argument is not NULLmID then the ranking attribute and memberID of the first member with the same ranking attribute and an equal or higher memberID is returned or, in the absence of that, the first member with a higher ranking attribute.  The first argument is a Cursor which may be used in a subsequent findNext or findPrior command.  More at findFirst. If the specified member cannot be found the RAandMID has RM_memberID equal to NULLmID.

RAandMID findEqualOrLower (Cursor * cuPtr, RAType ra, memberType mID) ;      

Returns an RAandMID containing the ranking attribute and memberID of the highest ranking member with ranking attribute equal to or less than that specified.  If the third argument is not NULLmID then it returns either the ranking attribute and memberID of the highest ranked member with the same ranking attribute and a lower memberID or, if none such exists, with a lower ranking attribute.  The first argument is a Cursor that can be used in a subsequent findNext or findPrior command. More at findFirst. If the specified member cannot be found the RAandMID has RM_memberID equal to NULLmID.  

RAandMID findAsInstructed (Cursor * cuPtr, findInstruction fI) ;

Behaves like findEqual, findEqualOrHigher or findEqualOrLower depending on the value of the second argument. More at findEqual, etc. Also see the findInstruction filedef. Note there that the present routine will also find NextHigherorNextLower

RemoveReturnCode removeThisCursorFromSet (Cursor * cuPtr) ;

Removes the specified Cursor from the set.

Class Cursor {

The find commands of RankedSet have a Cursor * argument. See RankedSet’s findFirst and Cursor's findNext for examples of typical usage.

RAType Cu_rankingAtt ( ) {return cu_rankingAtt;}

MemberType Cu_memberID ( ) {return cu_memberID;}

These routines return, respectively, the values of the ranking attribute and the member ID of the member at the Cursor’s current location. Use CuState( ) to check the status of the Cursor. It is permitted for a member to be removed from a set while a Cursor is "pointing" at it.  More at findNext.

Cursor ( ) ;

~Cursor ( ) ;

Default constructor and destructor.

Cu_Status CuState ( ) {return cuState;}

Returns the status of Cursor. See the Cu_Status filedef. CuState ( ) equal either Loose or Bound indicates that the Cursor is "in" a set. So, of course does

   if  (CuPtr®CuState( ) != NotInSet)

A Cursor can go from Bound to Loose when a member at its current location is removed from the set. This does not affect the response to a subsequent findNext or findPrior.

RAandMID findNext ( ) ;

Returns an RAandMID with the ranking attribute and memberID of the member—currently in the set—which follows (or would follow) the member previously "pointed at" by the Cursor, whether or not the latter member is still in the set. The Cursor remembers which set it is in. (This is not a public attribute of Cursor). If there is not a "next" member, the returned RAandMID has its RM_memberID equal to NULLmID.  Using the example in findFirst the SIMSCRIPT  II  statements (not case sensitive)

      For each job in queue (MG)

         DO

         ...

         Loop

would typically be implemented in C++EAS-E as

     for (RM=mgPtr→queue. findFirst (cuPtr);

       Cuptr→CuState()!=NotInSet;

       RM=CuPtr→findNext () )

   {

       J=(job*)RM.RM_memberID;

        ...

   }

RAandMID findPrior ( ) ;

Returns an RAandMID with the ranking attribute and memberID of the member--currently in the set--which precedes (or would precede) the member previously "pointed at" by the Cursor. More at findNext.

RAandMID findNextOrPrior (direction d) ;

Acts like findNext or findPrior depending on the value of the argument. See the direction filedef.