Name

pelem_search − Searches for the next matching element in the specified structure. 

Operating States: PHOP, ∗, ∗, ∗
PHIGS standard function

Syntax

void pelem_search (
  Pint                   stid,           /∗ (I) Structure identifier ∗/
  Pint                   start_elem,     /∗ (I) Starting element position∗/
  Psearch_dir            dir,            /∗ (I) Search direction ∗/
  const Pelem_type_list ∗incl,           /∗ (I) Inclusion set ∗/
  const Pelem_type_list ∗excl,           /∗ (I) Exclusion set ∗/
  Pint                  ∗err_ind,        /∗ (O) Error indicator ∗/
  Psearch_status        ∗status,         /∗ (O) Search status ∗/
  Pint                  ∗found_elem_ptr  /∗ (O) Found element pointer ∗/
)

See Constants for the list of element types.

Data Structures

typedef enum {
    PDIR_BACKWARD,    /∗ do a backward search ∗/
    PDIR_FORWARD      /∗ do a forward search ∗/
} Psearch_dir;
typedef struct {
    Pint          num_elem_types;    /∗ number of element types ∗/
    Pelem_type   ∗elem_types;        /∗ list of element types ∗/
} Pelem_type_list;
typedef enum {
    PSEARCH_STATUS_FAILURE,    /∗ search was unsuccessful ∗/
    PSEARCH_STATUS_SUCCESS     /∗ search was successful ∗/
} Psearch_status;

Description

pelem_search searches for the next matching element in the specified structure, beginning at the specified start point and continuing in the specified search direction. The search ends when the element is found, or when the function reaches the limits of the structure. 

The function will select an element if it is not a member of the element exclusion set and is a member of the element inclusion set.  If an element is included in both the inclusion and exclusion sets, the function excludes the element. 

If the start position is less than 0, the function begins the search at element 0.  If the start position is greater than the number of elements in the structure, the function begins the search at the last element in the open structure. 

If the search succeeds, the function returns the status indicator PSEARCH_STATUS_SUCCESS, and found_elem_ptr points to the matching element.  If the search fails, the function returns the PSEARCH_STATUS_FAILURE status indicator and the value of the found_elem_ptr is implementation-dependent. 

See Also

pincr_spa_search
pset_elem_ptr