List Methods
Introduction | List | Element | Array Methods
List Expansion Methods | List Contraction Methods | List Traversal Methods
Introduction
Several MPI objects maintain a list whose elements are other MPI objects.
| Example | A Motion object maintains a list of Axis objects. An EventMgr object maintains 2 lists: a list of Control objects and a list of Notify objects. |
The MPI declares standard list manipulation methods for all such objects. The MPI does not specify how lists are to be implemented.
List
A list is an ordered sequence of elements. Generally, the elements of a list are objects of the same type, but this is not required. A list that contains no elements is empty. A list may be traversed either forwards or backwards from any element that is a member of the list. List manipulation methods are declared for the object that maintains the list.
Element
An element is a member of a list. An element is generally an object. An element is added to or removed from a list using list manipulation methods (declared by the object that maintains the list).
| List Action | Description |
| ListGet ListSet |
Get list of elements associated with an object Create a list of elements associated with an object |
| Append Insert |
Append element to list Insert element into list associated with an object |
| Remove | Remove handle to object in list |
Count First Index Last Next Previous |
Return handle of indexth element |
Array Methods
You use Array methods to manipulate lists. Array methods use an element count and an application-resident array of elements. These methods provide a convenient way of dealing with a list as a whole. Note that if you do use array methods for list manipulation, you can also use other list manipulation methods as well.
mpiListElementListGet(MPIList list, long *count, MPIElement *Element)
The ListGet method returns the list (maintained by List) as an array of object handles of type MPIElement. Upon successful return of the ListGet method, the contents of the location pointed to by count will be set to the number of elements in the list, or set to zero (if the list is empty). Your application must also define the object handle array pointed to by Element, and the array must be large enough to hold the current number of list elements.
mpiListElementListSet(MPIList list, long count, MPIElement *Element)
The ListSet method sets the list (maintained by List) from an array of object handles of type MPIElement. Upon successful return of the ListSet method, the list will contain count elements. Your application must also define the object handle array pointed to by Element, and the array must contain at least count list elements. After using the ListSet method, any existing list will be completely replaced by the new list. To make an existing list empty, call the ListSet method with a count of 0 and Element set to NULL.
List Expansion Methods
A list can be expanded by inserting an element at any point, either as the first element of the list, after a specific list element, or as the last element of the list. Lists generally check and verify that an element to be inserted is not already a list element. Other list-specific checks may be made before insertion as well.
mpiListElementAppend(MPIList list, MPIElement Element)
The Append method appends an object (whose handle is Element) to the list maintained by List, making it the last element of the list.
mpiListElementInsert(MPIList list, MPIElement before, MPIElement insert)
The Insert method inserts an object (whose handle is insert) into the list maintained by List, placing it after the list element whose handle is before. If before is MPIHandleVOID, insert becomes the first element of the list.
List Contraction Methods
A list can be contracted (shortened) by removing a list element. Lists check and verify that the element to be removed is actually a list element.
mpiListElementRemove(MPIList list, MPIElement Element)
The Remove method removes an object (whose handle is Element) from the list maintained by List.
List Traversal Methods
To traverse a list means to be able to move through all of the elements on a list. It can also involve determining the number of list elements, searching for a particular list element, finding the index of a list element, and more.
MPIElement mpiListElement(MPIList list, long index)
| Return Values | Description |
| handle | of the indexth list element of the list maintained by List |
| MPIHandleVOID | if index is less than zero if index is greater-than-or-equal-to the number of list elements |
mpiListElementCount(MPIList list)
| Return Values | Description |
| number of list elements | on the list maintained by List |
-1 |
if list is invalid |
MPIElement mpiListElementFirst(MPIList list)
| Return Values | Description |
| handle | to the first list element of the list maintained by List |
| MPIHandleVOID | if list is empty or is not valid if list is not valid |
mpiListElementIndex(MPIList list, MPIElement Element)
| Return Values | Description |
| index | of Element in the list maintained by List |
-1 |
if list is empty or not valid if Element is not a list element of the list maintained by List |
MPIElement mpiListElementLast(MPIList list)
| Return Values | Description |
| handle | to the last list element of the list maintained by List |
| MPIHandleVOID | if list is empty if list is not valid |
MPIElement mpiListElementNext(MPIList list, MPIElement Element)
| Return Values | Description |
| handle | to the list element immediately after Element in the list maintained by List |
| MPIHandleVOID | if list is not valid if Element is not a list element if Element is the last list element of the list maintained by List |
MPIElement mpiListElementPrevious(MPIList list, MPIElement Element)
| Return Values | Description |
| handle | to the list element immediately before Element in the list maintained by list |
| MPIHandleVOID | if list is not valid if Element is not a list element if Element is the first list element of the list maintained by List |
| Event Notification Methods | List Methods | Identity Methods |