PEXElementSearch - Element Search (5.0)

Synopsis

 
   Status PEXElementSearch(
          Display *display,
          PEXStructure structure,
          int whence,
          long offset,
          int direction,
          unsigned long incl_count,
          unsigned short *incl_list,
          unsigned long excl_count,
          unsigned short *excl_list,
          unsigned long *elem_offset_return
   )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
structure: The resource identifier of the structure.
whence: A value specifying, with offset, the offset at which the search is to begin (PEXBeginning, PEXCurrent or PEXEnd).
offset: The offset from whence at which the search is to begin.
direction: The direction of the search (PEXForward or PEXBackward).
incl_count: The number of element types in the inclusion array.
incl_list: An array of element types to search for.
excl_count: The number of element types in the exclusion array.
excl_list: An array of element types not to search for.
elem_offset_return: Returns the offset of the element located by the search.

Returns

Zero if unsuccessful; non-zero otherwise. The non-zero value is either PEXFound or PEXNotFound depending upon the result of the search.

Description

Invoke PEXElementSearch to search for the first occurrence of the specified element type in the specified structure. The search always includes the starting element.

If the computed starting offset is less than zero, then it is set to zero before the search is performed. If the computed starting offset is greater than the number of elements in the structure, then it is set to the offset of the last element in the structure.

An element is selected if its element type is contained in the inclusion list (incl_list) and is not contained in the exclusion list (excl_list). An element type of PEXOCAll selects all element types, including OCNil. OCNil refers to the type of the implicit element at position 0. If a structure element type is in both the inclusion list and exclusion list, it is excluded.

The search terminates if a match is found or if the limits of the structure are reached. The search progresses from the start point in the specified direction (PEXForward or PEXBackward). This is a non-descending search; that is, the search does not include any referenced structures. If the search finds a match, then the function returns a return status of PEXFound and the offset of the matching element. If the search is unsuccessful, then the function returns a return status of PEXNotFound.

The element pointer position of structure is not changed, regardless of the returned search status.

Errors