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.

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

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)

mpiListElementCount(MPIList list)

MPIElement mpiListElementFirst(MPIList list)

mpiListElementIndex(MPIList list, MPIElement Element)

MPIElement mpiListElementLast(MPIList list)

MPIElement mpiListElementNext(MPIList list, MPIElement Element)

MPIElement mpiListElementPrevious(MPIList list, MPIElement Element)