All Frameworks  Class Hierarchy  This Framework  Previous  Next  Indexes

SPAkern Class ENTITY_LIST

SPAbase.ACIS_OBJECT
  |
  +---ENTITY_LIST

Usage: you must use this class as is. You should never derive it.

public class ENTITY_LIST

Implements a variable length list of entities with set and index behavior.

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 which rewinds the list and ENTITY_LIST::next which returns the next undeleted item.

The current implementation uses hashing so that look up is fast; 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){
 	.
	.
 	.
 	}
  }

Note: The general method for retrieving the number of entries in an ENTITY_LIST is iteration_count(). This function prevents having the list iterators skip deleted entries. Else some routines encounter arrays with uninitialized entries and unexpected results may occur.
If the count method is used to determine the number of entries in an ENTITY_LIST (including tombstones), then individual members can be accessed with the index operator [ ].
Note: The index operator [ ] does not ignore "removed" entries).

Be sure to check the returned pointer for the constant LIST_ENTRY_DELETED (-1), which indicates a tombstone (removed entry) at that index.

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.

See also:: DEBUG_LIST

Constructor and Destructor Index

o ENTITY_LIST(): C++ constructor, creating an ENTITY_LIST.
o ENTITY_LIST(ENTITY_LIST const&): 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.
o ENTITY_LIST(int,ENTITY**,logical): C++ constructor, creating an ENTITY_LIST from an array.
o ~ENTITY_LIST(): C++ destructor, deleting an ENTITY_LIST.

Method Index

o add(ENTITY*,logical): Adds an entity to the list and returns its index number.
o add(ENTITY_LIST const&,logical): Adds the entities of an ENTITY_LIST to this ENTITY_LIST.
o array(ENTITY**,int&,logical): Gets an array of the entities in the list.
o byte_count(logical): Returns the size in bytes of this class.
o clear(): Clear all entries from the list and reset indexes and counters for reuse.
o count(): Returns the number of entries in the list including the deleted ones (tombstones).
o first(): Returns the first undeleted (live) entry and updates the iterator correctly for the next method.
o init(): Initializes the iterator, which is used by the next method, to the beginning of the list.
o iteration_count(): Returns the number of live entities in the list not including deleted entries.
o lookup(ENTITY const*): Lookup the specified ENTITY in the list and return its index.
o next(): Returns the next undeleted (live) entry.
o next_from(int&): Returns the next non deleted entry after the index given without affecting the member variables used by init and next.
o operator=(ENTITY_LIST const&): Assignment operator performs a full copy of the list, complete with tombstones for deleted entries so that the indices are the same.
o operator[](int): Returns the entity at the given index from the list.
o remove(ENTITY const*): Remove the specified entry from the list and return its index.
o remove(ENTITY_LIST const&): Removes entities in the given list from the list; however, it does not free space.
o remove(int): Remove the entry at the specified index from the list and return its index.
o reverse(logical): Reverses the order of the entity list.
o sort(int(*compare_func)(const void* ent1, const void* )): Sorts the list based upon the user-supplied comparison function.

Constructor and Destructor

o ENTITY_LIST

public ENTITY_LIST(

)

C++ constructor, creating an ENTITY_LIST.

o ENTITY_LIST

public 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.

Parameters:

list_copy: list to copy.

o ENTITY_LIST

public ENTITY_LIST(	int	`count`,
	ENTITY**	`entity_array`,
	logical	`check`	`= TRUE` )

C++ constructor, creating an ENTITY_LIST from an array.

o ~ENTITY_LIST

public ~ENTITY_LIST(

)

C++ destructor, deleting an ENTITY_LIST.

Methods

o add

public int 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.

Parameters:

entity_name: entity name.
check: check unique.

o add

public void 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.

Parameters:

entity_list: entity list.
check: check unique.

o array

public ENTITY 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

Parameters:

entity_array: pointer of array to be used if provided.
array_count: number of entities in array.
tombstones: add tombstones to array.

o byte_count

public int 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.

Parameters:

countSelf: count self or not.

o clear

public void clear(

)

Clear all entries from the list and reset indexes and counters for reuse.

o count

public int count(

)const

Returns the number of entries in the list including the deleted ones (tombstones).

o first

public ENTITY * first(

)const

Returns the first undeleted (live) entry and updates the iterator correctly for the next method.

o init

public void init(

)const

Initializes the iterator, which is used by the next method, to the beginning of the list.

o iteration_count

public int iteration_count(

)const

Returns the number of live entities in the list not including deleted entries.

o lookup

public int lookup( ENTITY const* )const

Lookup the specified ENTITY in the list and return its index.

Parameters:

entry: entry to lookup

o next

public ENTITY * next(

)const

Returns the next undeleted (live) entry.

o next_from

public 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.

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.

Parameters:

inte: integer.

o operator=

public 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.

Parameters:

entity_list: entity list.

o operator[]

public ENTITY * 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.

Parameters:

index: integer.

o remove

public int 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.

Parameters:

entity_name: entry to remove

o remove

public void 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.

Parameters:

entity_list: entity list.

o remove

public int 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.

Parameters:

index: index of entry to remove.

o reverse

public void reverse( logical compress = TRUE )

Reverses the order of the entity list.

Role: If the compress flag is TRUE, deleted entities are removed.

Parameters:

compress: remove deleted entities.

o sort

public void sort( int(*compare_func)(const void* ent1, const void* ) ent2)

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.

Parameters:

compare_func: comparison function

This object is included in the file: lists.hxx