ENTITY_LIST
List of: Classes
Subjects: Entity, SAT Save and Restore
Contents: Kernel

Purpose: Implements a variable length list of entities.

Derivation: ENTITY_LIST : ACIS_OBJECT : -

Filename: kern/kernel/kerndata/lists/lists.hxx

Description: This class provides a constructor (which creates an empty list), a destructor, a function to add an entity (only if not already there), a function to look up an entity by pointer value, and a function to count the number of entities listed. Also provides an overloaded "[ ]" operator for access by position. This was created using the LIST macro.


The preferred way of accessing the data items is through ENTITY_LIST::init which rewinds the list and ENTITY_LIST::next which returns the next undeleted item


For best performance in loops that step through this list by index value, have the loops increment rather than decrement the index counter. Internal operations for methods like operator[] and remove store the index counter from the previous operation allowing faster access to the next indexed item when indexing up.


The functions are all essentially dummy; just indirecting through the header pointer. This is done in order to insulate the application programs completely from the implementation of lists.


The current implementation uses hashing so that look up is fast provided lists are not very long; it is also efficient for very short lists and for repeated lookups of the same entity.


When a group of similar arguments must be returned, and the number of arguments is not known in advance, the system returns the arguments as an ENTITY_LIST. For instance, when the routine api_cover_sheet is used to find every simple loop of external edges of a sheet body, the faces made are put into an ENTITY_LIST that is returned.


ENTITY_LIST my_face_list;

api_cover_sheet(sheet_body, new_surface,


my_face_list);

ENTITY* my_list_item

my_face_list.init();

while ((my_list_item=my_face_list.next()) != NULL){


if is_FACE(my_list_item){


.


.


.


}

}


The number of members of an ENTITY_LIST can be found using the member function count, and individual members can be accessed with the subscript operator [ ].


Some routines expect arrays of input arguments. Because the length of the array is known before the API routine is called, these are passed as an integer giving the length of the array followed by an array (in fact a pointer to the first element of an array). For example, api_cover_wires covers one or more circuits of edges with a face. Each circuit is held in a wire body and so the two input arguments are an integer and BODY*[ ].


The ENTITY_LIST class is a variable length associative array of ENTITY pointers. When using the subscript operator, a cast is required to change the ENTITY pointer into the correct type. Many ACIS internal algorithms use ENTITY_LIST including the part copy, save, and restore algorithms. ENTITY_LIST is also useful in ACIS components and applications.

References: by KERN DEBUG_LIST, EE_LIST, HISTORY_STREAM, entity_notification_handler, msh_sur, net_spl_sur, pattern_holder, restore_data, scan_list

Constructor: public: ENTITY_LIST::ENTITY_LIST ();


C++ constructor, creating an ENTITY_LIST.






public: ENTITY_LIST::ENTITY_LIST (


ENTITY_LIST const& // list to copy


);


C++ copy constructor, which copies the whole list (complete with deleted entries, if any), so that the indices in the copy match those in the original.




Destructor: public: ENTITY_LIST::~ENTITY_LIST ();


C++ destructor, deleting an ENTITY_LIST.



Methods: public: int ENTITY_LIST::add (


ENTITY* // entity name


);


Add an entity to the list and returns its index number.






public: virtual int ENTITY_LIST::byte_count (


logical countSelf
// count self or not



= TRUE


) const;


Returns the size in bytes of this class. It does not include the size of the individual ENTITIES themselves.






public: void ENTITY_LIST::clear ();


Empties a list for construction of a new one.






public: int ENTITY_LIST::count () const;


Returns the number of entities to a given list.






public: void ENTITY_LIST::init () const;


Initializes the correct position in the list for next.






public: int ENTITY_LIST::iteration_count () const;


Counts how many entities there are in the list not including deleted entries. Uses the iterator.






public: ENTITY* ENTITY_LIST::next () const;


Returns the next undeleted entry.






public: ENTITY* ENTITY_LIST::next_from (


int&, // integer


);


Return the next non deleted entry after the index given without affecting the member variables used by init and next. This allows clients to create iterators that can be multiply instantiated and which run independently of each other. This is accomplished simply by giving the the user the appropriate variables to save themselves.






public: ENTITY_LIST& ENTITY_LIST::operator= (


ENTITY_LIST const& // entity list


) ;


Assignment operator. This performs a full copy of the list, complete with tombstones for deleted entries so that the indices are the same.






public: ENTITY* ENTITY_LIST::operator[] (


int
// integer


) const;


Returns a given item from a list.






public: int ENTITY_LIST::remove (


ENTITY const* // entity name


);


Deletes an entity from the list; however, it does not free space.






public: int ENTITY_LIST::remove (


int
// integer


);


Deletes an entity from the list; however, it does not free space.






public: void ENTITY_LIST::reverse (


logical compress // remove deleted



= TRUE // entities


);


Reverses the order of the entity list. If the compress flag is TRUE, deleted entities are removed.
PDF/KERN/31CLE.PDF
HTM/DATA/KERN/KERN/31CLE/0010.HTM