All Frameworks  Class Hierarchy  This Framework  Previous  Next  Indexes

SPAasm Class component_handle_list

SPAbase.ACIS_OBJECT
  |
  +---component_handle_list

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

public class component_handle_list

Implements a variable length list of component handles with set and index behavior and optional holding and counting mechanisms.

Role: This class is a list object for component_handle objects that is intended to have the look and feel of the ENTITY_LIST class. But the functionality has been extended to include holding and counting mechanisms.

If the counting mechanism is turned on, then the list keeps track of the entry count, i.e. the number of times the same entry has been added minus the number of times it has been removed. The entry is deleted from the list only if the entry count reaches zero.
When the holding state of the list is set to ASM_HOLD, the list increments the use count of each entry. This ensures that "held" entries are not deleted when the handles are cleaned up. For details on cleaning up handles, please refer to the documentation on the asm_model object.
The holding and counting mechanisms are specified when the component_handle_list object is constructed. Additionally, the holding state can be changed using component_handle_list::set_hold_state.

Handles are added to the end of the list using component_handle_list::add which ensures that the handles are not already in the list (i.e. set behavior). The component_handle_list::remove methods take entries off the list, but a tombstone remains at the position of the former entries. The component_handle_list::add_notify and component_handle_list::remove_notify methods notify the caller when the list is actually modified.
The position of current entries can be determined using component_handle_list::lookup, and the entry at a specified position may be accessed using the overloaded "[ ]" index operator. The number of entries in the list is returned by component_handle_list::count (includes tombstones) and component_handle_list::iteration_count (excludes tombstones). The preferred way of accessing the data items is through component_handle_list::init which rewinds the list and component_handle_list::next which returns the next undeleted item. The component_handle_list::first method rewinds the list and returns the first non-deleted entry.

The current implementation uses hashing so that component_handle_list::lookup is fast; it is also efficient for very short lists and for repeated lookups of the same component handle.

When a group of component handles must be returned, and the number of arguments is not known in advance, the system returns the arguments as an component_handle_list. For instance, when the routine asm_get_sub_components is used to find the child components of a component, the handles found are put into an component_handle_list that is returned.

 component_handle_list my_handles;
 asm_get_sub_components( comp_handle, my_handles );
 for ( component_handle* handle = my_handles.first(); handle != NULL; handle = my_handles.next() )
 {
 .
 .
 .

 }

Note: The general method for retrieving the number of entries in an component_handle_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 component_handle_list (including tombstones), then individual entries 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.

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

See also:: component_handle

Constructor and Destructor Index

o component_handle_list(): Default constructor, creating an component_handle_list.
o component_handle_list(asm_hold_state): C++ constructor, creating an component_handle_list with the specified holding behavior.
o component_handle_list(asm_list_options*): C++ constructor, creating an component_handle_list with the behavior specified by the asm_list_options object.
o component_handle_list(component_handle_list&): 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 component_handle_list(int,component_handle**,asm_list_options*,logical): C++ constructor, creating an component_handle_list from an array with the behavior specified by the asm_list_options object.
o ~component_handle_list(): C++ destructor, deleting an component_handle_list.

Method Index

o add(component_handle*,logical): Adds a component handle to the list and returns its index number.
o add(component_handle_list&,logical): Adds the handles of an component_handle_list to this component_handle_list.
o add_notify(component_handle*,logical&,int&): Adds a component handle to the list, returns its index number and notifies if the handle is new

Role:Same as component_handle_list::add, but notifies the caller if the handle is added to the list for the first time and returns the entry count for the added entry.
o array(component_handle**,int&,logical): Gets an array of the component handles 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 entry_count(component_handle*): Returns the number of times an entry has been added minus the number of times it has been removed.
o entry_count(int): Returns the number of times an entry has been added minus the number of times it has been removed.
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 entries in the list not including deleted entries.
o lookup(component_handle*): Lookup the specified asmsembly handle 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=(component_handle_list&): 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 component handle at the given index from the list.
o remove(component_handle*): Remove the specified entry from the list and return its index.
o remove(component_handle_list&): Removes asm handles 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 remove_notify(component_handle*,logical&,int&): Remove the specified entry from the list and return its index.
o reverse(logical): Reverses the order of the component handle list.
o set_hold_state(asm_hold_state): Sets the hold state of the handle list.
o sort(int(*compare_func)(const void* handle1, const void* )): Sorts the list based upon the user-supplied comparison function.

Constructor and Destructor

o component_handle_list

public component_handle_list(

)

Default constructor, creating an component_handle_list.

Role: By default, the hold state is set to ASM_NO_HOLD and the counting mechanism is turned off.

See also:: asm_hold_state

o component_handle_list

public component_handle_list( asm_hold_state state)

C++ constructor, creating an component_handle_list with the specified holding behavior.

Role: By default, the counting mechanism is turned off.

Parameters:

state: hold state.

See also:

asm_hold_state

o component_handle_list

public component_handle_list( asm_list_options* list_opts)

C++ constructor, creating an component_handle_list with the behavior specified by the asm_list_options object.

Parameters:

list_opts: pointer to assembly list options.

See also:

asm_list_options

o component_handle_list

public component_handle_list( const component_handle_list& 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.

Role: If holding is turned on, the use count of all active entries is incremented. For counted lists, the number of times each entry has been added is also copied.

Parameters:

list_copy: list to copy.

o component_handle_list

public component_handle_list(	int	`count`,
	component_handle**	`handle_array`,
	asm_list_options*	`list_opts`	`= NULL`,
	logical	`check`	`= TRUE` )

C++ constructor, creating an component_handle_list from an array with the behavior specified by the asm_list_options object.

Role: If the check flag is set to FALSE, the elements of the array are not checked to ensure that the entries of the list are unique.

Parameters:

count: size of array
handle_array: array of component handles
list_opts: pointer to assembly list options.
check: check unique.

See also:

asm_list_options

o ~component_handle_list

public ~component_handle_list(

)

C++ destructor, deleting an component_handle_list.

Role: If holding is turned on, the use counts of all entries are decremented.

Methods

o add

public int add(	component_handle*	`handle`,
	logical	`check`	`= TRUE` )

Adds a component handle 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. If holding is turned on, the handle's use count is incremented the first time it is added to the list. If the counting mechanism is turned on, the entry count for the added entry is incremented.

Parameters:

handle: component_handle to add.
check: check unique.

o add

public void add(	const component_handle_list&	`handle_list`,
	logical	`check`	`= TRUE` )

Adds the handles of an component_handle_list to this component_handle_list.

Role:Same as component_handle_list::add for all handles in the input list.

Parameters:

component_handle_list: component_handle list.
check: check unique.

o add_notify

public int add_notify(	component_handle*	`handle`,
	logical&	`was_added`,
	int&	`entry_count`)

Adds a component handle to the list, returns its index number and notifies if the handle is new

Role:Same as component_handle_list::add, but notifies the caller if the handle is added to the list for the first time and returns the entry count for the added entry.

Parameters:

handle: component_handle to add.
was_added: notify if new on list.
entry_count: number of adds minus removes

o array

public component_handle array**(	component_handle**	`handle_array`	`= NULL`,
	int&	`array_count`	`= (int )NULL_REF`,
	logical	`tombstones`	`= FALSE` )

Gets an array of the component handles in the list.

Role: The default returns an array that must be freed by using ACIS_DELETE [] STD_CAST

Parameters:

handle_array: pointer of array to be used if provided.
array_count: number of handles 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 component_handles 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.

Role: If holding is turned on, the use count of all active entries of the list is decremented before being removed from the list. The holding and counting behavior of the list remains unchanged.

o count

public int count(

)const

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

o entry_count

public int entry_count( const component_handle* list_member)

Returns the number of times an entry has been added minus the number of times it has been removed.

Role: This method returns -1 if counting is turned off or the list member is not found.

Parameters:

list_member: component handle.

o entry_count

public int entry_count( int index)

Returns the number of times an entry has been added minus the number of times it has been removed.

Role: This method returns -1 if counting is turned off, the index corresponds to a deleted entry or the index is out of range.

Parameters:

index: integer.

o first

public component_handle * 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 entries in the list not including deleted entries.

o lookup

public int lookup( const component_handle* handle)const

Lookup the specified asmsembly handle in the list and return its index.

Parameters:

handle: entry to lookup

o next

public component_handle * next(

)const

Returns the next undeleted (live) entry.

o next_from

public component_handle * next_from( int& index)

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:

index: integer.

o operator=

public component_handle_list& operator=( const component_handle_list& component_handle_list)

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

Role: If holding is turned on, the use count of all active entries of the original list is decremented and the use count of all entries of the copied list is incremented. For counted lists, the entry count for each entry is also copied.

Parameters:

component_handle_list: component_handle list.

o operator[]

public component_handle * operator[]( int index)const

Returns the component handle 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 component handle was removed from the list.

Parameters:

index: integer.

o remove

public int remove( const component_handle* handle)

Remove the specified entry from the list and return its index.

Role: If the counting mechanism is turned on and entry count of the specified entry is greater than one, then that count is decremented and the entry is not actually deleted from the list. The entry is deleted from the list only when the entry count reaches zero. When the entry is deleted from the list, a tombstone is left in its place. The count of the list is not reduced, the iteration_count, however, is. If holding is turned on, the handle's use count is decremented when the object is deleted from the list.

Parameters:

handle: entry to remove

o remove

public void remove( const component_handle_list& handle_list)

Removes asm handles in the given list from the list; however, it does not free space.

Role: Same as component_handle_list::remove for a list of handles.

Parameters:

handle_list: component_handle list.

o remove

public int remove( int index)

Remove the entry at the specified index from the list and return its index.

Role: Same as component_handle_list::remove.

Parameters:

index: index of entry to remove.

o remove_notify

public int remove_notify(	const component_handle*	`handle`,
	logical&	`was_removed`,
	int&	`entry_count`)

Remove the specified entry from the list and return its index.

Role: Same as component_handle_list::remove, but the caller is notified if the entry is actually deleted the list and the entry count of the removed entry is returned.

Parameters:

handle: entry to remove
was_removed: notify if deleted from list.
entry_count: number of adds minus removes

o reverse

public void reverse( logical compress = TRUE )

Reverses the order of the component handle list.

Role: If the compress flag is TRUE, tombstones associated with deleted handles are removed.

Parameters:

compress: remove deleted entries.

o set_hold_state

public void set_hold_state( asm_hold_state state)

Sets the hold state of the handle list.

Role: If holding is turned on, the use count of all active entries of the list is incremented.

Parameters:

state: hold state.

See also:

asm_hold_state

o sort

public void sort( int(*compare_func)(const void* handle1, const void* ) handle2)

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 handle1 is less than handle2, greater than zero if handle1 is greater than handle2, and zero if they are the same. Tombstones are removed bofore sorting and do not have to be considered by the compare 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: comp_handle_list.hxx