HC_Begin_Segment_Search
-
void
HC_Begin_Segment_Search(char const *segspec) - void HC_Begin_Segment_Search(char const segspec)
Finds all segments matching a search specification.
Begin_Segment_Search() initiates the search by specifying where to start looking for segments.
Show_Segment_Count() lets a program anticipate how many segments names will be returned from a sequence of calls to Find_Segment() in order that sufficient space may be allocated to receive them. Count is the total number of matching segments.
Find_Segment() is the routine that returns, one at a time, the segments which matched the specification given in Begin_Segment_Search(). When all segments have been returned, its function value becomes false.
End_Segment_Search() terminates the search sequence and reactivates any previously active segment search.
The segspec parameter can take a number of valid segment name specifications including aliases, wildcards, and paths, as explained in the HOOPS/3dGS programming guide section 1.2.6 “Segment-Name Syntax”. Wildcards in the segment specification will typically match more than one segment in the database. The following examples are valid usages:
- “*” Returns the currently open segment and all children, but no grandchildren.
- “.” Returns the currently open segment.
- “..” Returns the parent of the currently open segment.
- “…” Returns the currently open segment, and all subsegments.
- “….” Returns the currently open segment, all subsegments, and any include segments below the current segment.
- “?picture/model” Returns the segment “model”.
- “?picture/model/..” Returns “?picture”.
- “?picture/model/…” Returns the segment named ‘model’ and all of its subsegments.
- “?picture/model/….” Returns the segment named ‘model’, all of its children, and any include segments below ‘model’.
- “/…/model*” Returns all segments in the entire tree starting with ‘model’, but not their subsegments.
- “/…/model/….” Searches all segments in the entire tree named ‘model’, their children, and any include segments below them.
The Begin_Segment_Search() operations can be nested. This allows a program to “walk the tree” as in the following recursive example (written in C) which prints the names of all the children in the subtree of a given segment:
level = 0 print_children (segment) { Open_Segment (segment) Begin_Segment_Search ("*") while (Find_Segment (child)) { Parse_String (child, "/", -1, pathname) print (level, pathname) level = level + 1 print_children (pathname) level = level - 1 } End_Segment_Search () Close_Segment () }
This example could also have been written using the “contents search” routines, replacing “Begin_Segment_Search (”*”)” with “Begin_Contents_Search (“.”, “segments”)”, and so on.
If a search is in progress and a segment satisfying the target specification is deleted, it will not be returned by subsequent calls to Find_Segment() . If a segment is renamed, the new name will be returned. If a segment is created, it will not be returned in the current sequence of Find_Segment() calls.
Show_Segment_Count() must be called between Begin_Segment_Search() and End_Segment_Search() . It will always return the total* number of segments, not the remaining number of segments.
HC_Begin_Contents_Search, HC_Begin_Open_Segment_Search, HC_Show_Existence, HC_Open_Segment.Parameters
segspec: A specification, often including wildcards, of the segment(s) to be searched for. Passed by reference always