#include <lists.hxx>
Public Member Functions | |
| void | add (ENTITY_LIST const &entity_list, logical check=TRUE) |
Adds the entities of an ENTITY_LIST to this ENTITY_LIST. | |
| int | add (ENTITY *entity_name, logical check=TRUE) |
| Adds an entity to the list and returns its index number. | |
| ENTITY ** | array (ENTITY **entity_array=NULL, int &array_count=*(int *) NULL_REF, logical tombstones=FALSE) |
| Gets an array of the entities in the list. | |
| int | byte_count (logical countSelf=TRUE) const |
| Returns the size in bytes of this class. | |
| void | clear () |
| Clear all entries from the list and reset indexes and counters for reuse. | |
| int | count () const |
| Returns the number of entries in the list including the deleted ones (tombstones). | |
| ENTITY_LIST (ENTITY_LIST const &list_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. | |
| ENTITY_LIST (int count, ENTITY **entity_array, logical check=TRUE) | |
C++ constructor, creating an ENTITY_LIST from an array. | |
| ENTITY_LIST () | |
C++ constructor, creating an ENTITY_LIST. | |
| ENTITY * | first () const |
| Returns the first undeleted (live) entry and updates the iterator correctly for the next method. | |
| void | init () const |
| Initializes the iterator, which is used by the next method, to the beginning of the list. | |
| int | iteration_count () const |
| Returns the number of live entities in the list not including deleted entries. | |
| int | lookup (ENTITY const *) const |
| Lookup the specified ENTITY in the list and return its index. | |
| ENTITY * | next () const |
| Returns the next undeleted (live) entry. | |
| ENTITY * | next_from (int &inte) |
Returns the next non deleted entry after the index given without affecting the member variables used by init and next. | |
| ENTITY_LIST & | operator= (ENTITY_LIST const &entity_list) |
Assignment operator performs a full copy of the list, complete with tombstones for deleted entries so that the indices are the same. | |
| ENTITY * | operator[] (int index) const |
| Returns the entity at the given index from the list. | |
| int | remove (int index) |
| Remove the entry at the specified index from the list and return its index. | |
| void | remove (ENTITY_LIST const &entity_list) |
| Removes entities in the given list from the list; however, it does not free space. | |
| int | remove (ENTITY const *entity_name) |
| Remove the specified entry from the list and return its index. | |
| void | reverse (logical compress=TRUE) |
| Reverses the order of the entity list. | |
| void | sort (int(*compare_func)(const void *ent1, const void *ent2)) |
| Sorts the list based upon the user-supplied comparison function. | |
| ~ENTITY_LIST () | |
C++ destructor, deleting an ENTITY_LIST. | |
Role: This class provides a constructor (which creates an empty list), a destructor (which returns used memory), a function to add an entity if not already in the list (i.e. set behavior), a function to remove an entry (leaving a tombstone), a function to look up an entity by pointer value or index, a function to count the number of entries in the list (including tombstones), and a function to return the number of live entries in the list (iteration_count) excluding the tombstones. Also provides an overloaded "[ ]" index operator for access by position.
The preferred way of accessing the data items is through ENTITY_LIST::init method, which rewinds the list; and ENTITY_LIST::next method, which returns the next undeleted item. Using init and next will avoid removed entries, i.e., tombstones.
The current implementation uses hashing. This results in efficient searching, inserting, and deleting of entries. Furthermore, this data structure has been tuned so that it is efficient for both small lists and large lists, as well as repeated lookups of the same entity.
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){ } }
ENTITY_LIST is not an ENTITY. Therefore, it cannot be saved to SAT/SAB, nor can it "roll" within history. ENITTY in added to the ENTITY_LIST then subsequently lost, a stale pointer will reside within the ENTITY_LIST. In other words, the ENTITY_LIST has no knowledge of the lifetime of any of its entries. SPACOLLECTION entity if you need a container that stores a list of entities, can be saved/restored, can roll through history, and has knowledge of the lifetime of its members. first and next methods will result in efficient list traversal and will avoid tombstone entries. Using the array-operator to index entries is efficient for front-to-back list traversal, but is less efficient when randomly accessing entries. Also, indexing using the array-operator will return tombstone entries. LIST_ENTRY_DELETED (-1). iteration_count method. The count method will return the count of entries in the list including tombstones. | ENTITY_LIST::ENTITY_LIST | ( | ) |
C++ constructor, creating an ENTITY_LIST.
| ENTITY_LIST::~ENTITY_LIST | ( | ) |
C++ destructor, deleting an ENTITY_LIST.
| ENTITY_LIST::ENTITY_LIST | ( | int | count, | |
| ENTITY ** | entity_array, | |||
| logical | check = TRUE | |||
| ) |
C++ constructor, creating an ENTITY_LIST from an array.
| ENTITY_LIST::ENTITY_LIST | ( | ENTITY_LIST const & | list_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.
| list_copy | list to copy. |
| void ENTITY_LIST::add | ( | ENTITY_LIST const & | entity_list, | |
| logical | check = TRUE | |||
| ) |
Adds the entities of an ENTITY_LIST to this ENTITY_LIST.
Role: If the check flag is FALSE, then the lookup that assures a unique entry is skipped.
| entity_list | entity list. | |
| check | check unique. |
| int ENTITY_LIST::add | ( | ENTITY * | entity_name, | |
| logical | check = TRUE | |||
| ) |
Adds an entity to the list and returns its index number.
Role: If the check flag is set to FALSE, then the lookup that assures a unique entry is skipped.
| entity_name | entity name. | |
| check | check unique. |
| ENTITY** ENTITY_LIST::array | ( | ENTITY ** | entity_array = NULL, |
|
| int & | array_count = *(int *) NULL_REF, |
|||
| logical | tombstones = FALSE | |||
| ) |
Gets an array of the entities in the list.
Role: The default returns the an array that must be freed by using ACIS_DELETE [] STD_CAST
| entity_array | pointer of array to be used if provided. | |
| array_count | number of entities in array. | |
| tombstones | add tombstones to array. |
| int ENTITY_LIST::byte_count | ( | logical | countSelf = TRUE |
) | const |
Returns the size in bytes of this class.
Role: It does not include the size of the individual ENTITIES themselves.
| countSelf | count self or not. |
| void ENTITY_LIST::clear | ( | ) |
Clear all entries from the list and reset indexes and counters for reuse.
| int ENTITY_LIST::count | ( | ) | const |
Returns the number of entries in the list including the deleted ones (tombstones).
| ENTITY* ENTITY_LIST::first | ( | ) | const |
Returns the first undeleted (live) entry and updates the iterator correctly for the next method.
| void ENTITY_LIST::init | ( | ) | const |
Initializes the iterator, which is used by the next method, to the beginning of the list.
| int ENTITY_LIST::iteration_count | ( | ) | const |
Returns the number of live entities in the list not including deleted entries.
| int ENTITY_LIST::lookup | ( | ENTITY const * | ) | const |
| ENTITY* ENTITY_LIST::next | ( | ) | const |
Returns the next undeleted (live) entry.
| ENTITY* ENTITY_LIST::next_from | ( | int & | inte | ) |
Returns the next non deleted entry after the index given without affecting the member variables used by init and next.
Role: 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.
| inte | integer. |
| ENTITY_LIST& ENTITY_LIST::operator= | ( | ENTITY_LIST const & | entity_list | ) |
Assignment operator performs a full copy of the list, complete with tombstones for deleted entries so that the indices are the same.
| entity_list | entity list. |
| ENTITY* ENTITY_LIST::operator[] | ( | int | index | ) | const |
Returns the entity at the given index from the list.
Role: This method returns NULL if the given index is out of range, or the constant LIST_ENTRY_DELETED if the indexed entity was removed from the list.
| index | integer. |
| int ENTITY_LIST::remove | ( | int | index | ) |
Remove the entry at the specified index from the list and return its index.
Role: Although the entry is removed from the list, a tombstone is left in its place. The count of the list is not reduced, the iteration_count, however, is.
| index | index of entry to remove. |
| void ENTITY_LIST::remove | ( | ENTITY_LIST const & | entity_list | ) |
Removes entities in the given list from the list; however, it does not free space.
Role: Although the entries are removed from the list, tombstones are left in their place. The count of the list is not reduced, the iteration_count, however, is.
| entity_list | entity list. |
| int ENTITY_LIST::remove | ( | ENTITY const * | entity_name | ) |
Remove the specified entry from the list and return its index.
Role: Although the entry is removed from the list, a tombstone is left in its place. The count of the list is not reduced, the iteration_count, however, is.
| entity_name | entry to remove |
| void ENTITY_LIST::reverse | ( | logical | compress = TRUE |
) |
Reverses the order of the entity list.
Role: If the compress flag is TRUE, deleted entities are removed.
| compress | remove deleted entities. |
| void ENTITY_LIST::sort | ( | int(*)(const void *ent1, const void *ent2) | compare_func | ) |
Sorts the list based upon the user-supplied comparison function.
Role: Implements the runtime qsort function to sort the list and expects the input compare funcion to have the same behavior as described for qsort. The return value should be less than zero if entity 1 is less than entity 2, greater than zero if entity 1 is greater than entity 2, and zero if they are the same. Tombstones are removed bofore sorting and do not have to be considered by the comprare function. The sorted list is obviously re-indexed, which may occur even when the list does not actually require sorting changes.
| compare_func | comparison function |