.

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
Return number of elements in list
Return handle to first element in list
Return index number of element in list
Return handle to last element in list
Return handle to next element in list
Return handle to previous element in list

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

Object Methods | Configuration Methods | Memory Methods | Status Methods
| Event Notification Methods | List Methods | Identity Methods |

       Legal Notice  |  Tech Email  |  Feedback
      
Copyright ©
2001-2010 Motion Engineering