SIMC - SET FUNCTIONS

Definitions

     A Set must be declared as Set_ID

     Set_ID   Set;                      /* C/C++ */

     and, in C only, initialised with

     Set = SetCreate();                 /* C */


     Data to be Saved in a Set should be a Pointer to the
     desired data type.

     With C++, classes that would be saved as Data must inherit
     SimC - an empty class - as follows:

     class Simulation_Class : public SimC    /* C++ */
     { ... }


Set_ID SetCreate( void);                /* C */

     Creates and initialise a Set.  It returns an identifier
     Set_ID which is required as the 1st parameter to all Set
     functions.


long SetClear( Set_ID Set);             /* C/C++ */
long Set_ID::Clear( void);              /* C++ */

     Clears the Set.  Returns the number of items Cleared.


long SetFind( Set_ID Set, Pointer Data);     /* C/C++ */
long Set_ID::Find( Pointer Data);            /* C++ */

     Returns an Index to the first occurrence of Data in Set,
     returns NULL if not found.


Pointer SetGet( Set_ID Set, long Index);     /* C/C++ */
Pointer Set_ID::Get( long Index);            /* C++ */

     Removes and returns the Data Saved at the Indexed position
     in Set, returns NULL if Index is less than 1 or greater
     than Set's size.


Pointer SetGetFirst( Set_ID Set, long Index);     /* C/C++ */
Pointer Set_ID::GetFirst( long Index);            /* C++ */

     macro/equivalent for SetGet( Set, 1).


Pointer SetGetLast( Set_ID Set, long Index);      /* C/C++ */
Pointer Set_ID::GetLast( long Index);             /* C++ */

     macro/equivalent for SetGet( Set, SetSize( Set)).


long SetKill( Set_ID Set);              /* C */
Set_ID::~Set_ID( void);                 /* C++ */

     Clears the Set, and initialise it to NULL.  Returns the
     number of items cleared upon completion.


long SetList( Set_ID Set, int ListRoutine( Pointer));
     /* C/C++ */
long Set_ID::List( int ListRoutine( Pointer));
     /* C++ */

     For each Data in Set, calls ListRoutine, passing Data as
     the parameter.


long SetRank( Set_ID Set, int RankRoutine( Pointer, Pointer));
     /* C/C++ */
long Set_ID::Rank( int RankRoutine( Pointer, Pointer));
     /* C++ */

     Ranks Data in Set with RankRoutine.  RankRoutine should
     accept 2 Data as parameters and should return 1 if the 1st
     Data ranks higher than the 2nd, 0 if they ranks equal, and
     -1 if 2nd ranks higher than the 1st.  Data are positioned
     ahead of data with lower ranks, behind data of higher
     ranks, and behind data of equal rank but was already ahead
     in position.  Returns the Size of the Set.


Pointer SetRead( Set_ID Set, long Index);    /* C/C++ */
Pointer Set_ID::Read( long Index);           /* C++ */

     Returns the Data at the position specified by Index,
     returns NULL if Index is less than 1 or greater than Set's
     size.


Pointer SetReadFirst( Set_ID Set);      /* C/C++ */
Pointer Set_ID::ReadFirst( void);       /* C++ */

     Macro/equivalent for SetRead( Set, 1);


Data SetReadLast( Set_ID Set);          /* C/C++ */
Data Set_ID::ReadLast( void);           /* C++ */

     Macro/equivalent for SetRead( Set, SetSize( Set));


Data SetReadNext( Set_ID Set);          /* C/C++ */
Data Set_ID::ReadNext( void);           /* C++ */

     Returns the Data after the Data that was accessed by the
     last Set-function eg after a SetRead( Set, 7), a
     SetReadNext( Set) will return the 8th Data.  After
     accessing the last Data or after a SetReadLast( Set), the
     next SetReadNext( Set) will return NULL.


long SetRemove( Set_ID Set, Pointer Data);   /* C/C++ */
long Set_ID::Remove( Pointer Data);          /* C++ */

     Removes the first occurrence of Data in Set.  Returns the
     Index to the position of Data in Set.  Returns NULL if Data
     is not found.


long SetSave( Set_ID Set, Pointer Data, long Index);
     /* C/C++ */
long Set_ID::Save( Pointer Data, long Index);
     /* C++ */

     Saves the Data at the position specified by Index.  Saves
     as first if Index is less than 1, and Saves as last if
     Index is greater than Set's size.  Returns the Index to the
     actual position Saved.


long SetSaveFirst( Set_ID Set, Pointer Data);     /* C/C++ */
long Set_ID::SaveFirst( Pointer Data);            /* C++ */

     Macro/equivalent for SetSave( Set, Data, 1);


long SetSaveLast( Set_ID Set, Pointer Data);      /* C/C++ */
long Set_ID::SaveLast( Pointer Data);             /* C++ */

     Saves Data as the last member of Set.  Returns the Index to
     the actual position Saved.


long SetSaveRanked( Set_ID Set, Pointer Data,
                    int RankRoutine( Pointer, Pointer));
     /* C/C++ */
long Set_ID::Ranked( Pointer Data, 
                 int RankRoutine( Pointer, Pointer));
     /* C++ */

     Saves Data in Set ranked with RankRoutine.  RankRoutine
     should accept 2 Data as parameters and should return 1 if
     the 1st Data ranks higher than the 2nd, 0 if they ranks
     equal, and -1 if 2nd ranks higher than the 1st.  Data will
     be Saved ahead of the 1st existing Data of lower ranks. 
     Returns the Index to the actual position Saved.


long SetSize( Set_ID Set);              /* C/C++ */
long Set_ID::Size( void);               /* C++ */

     returns Set's size - the number of Data saved in Set.


ForEach( D, Set)                        /* C/C++ */

     A macro:

     for( D= SetReadFirst( Set); D= SetReadNext( Set); D)

     that initialised D with the 1st Data in Set and iterate D
     with SetReadNext() until D is NULL.  During the iteration,
     random access Set- functions should be avoided as it would
     change the results of the next SetReadNext().


ForEachC( D, Cast, Set)                 /* C/C++ */

     A macro:

     for( D= (Cast*) SetReadFirst( Set); 
          D= (Cast*) SetReadNext( Set); D)


     that initialised D with the 1st Data in Set and iterate D
     with SetReadNext() until D is NULL, each time type-casting
     Data to Cast ie (Cast *) before assigning to D.  During the
     iteration, random access Set- functions should be avoided
     as it would change the results of the next SetReadNext().

