Begin_Segment_Search

Functions

void Begin_Segment_Search (const char *segspec)
 Finds all segments matching a search specification. More...
 
void End_Segment_Search (void)
 Terminates the segment search sequence and frees any involved memory. More...
 
HC_BOOLEAN Find_Segment (char *segment)
 Retrieves the segment names, one at a time. The function returns false when all segments have been returned. More...
 
void Show_Segment_Count (int *count)
 Finds out how many segments will be returned. This is useful for determining the size of a data structure needed to store incoming items. More...
 

Detailed Description

Function Documentation

◆ Begin_Segment_Search()

void Begin_Segment_Search ( const char *  segspec)

Finds all segments matching a search specification.

Parameters
segspec- A specification, often including wildcards, of the segment(s) to be searched for. Passed by reference always

DETAILS

The segment search routines provide the ability to determine the current segment structure of the database.
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.

NOTES

If no segments are found that match the specification, the first call to Find_Segment() returns false.
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.

RESTRICTIONS

See also
Begin_Contents_Search, Begin_Open_Segment_Search, Show_Existence, Open_Segment.

◆ End_Segment_Search()

void End_Segment_Search ( void  )

Terminates the segment search sequence and frees any involved memory.

DETAILS

No additional details. See Begin_Segment_Search()

◆ Find_Segment()

HC_BOOLEAN Find_Segment ( char *  segment)

Retrieves the segment names, one at a time. The function returns false when all segments have been returned.

Parameters
segment- The full pathname of a segment that satisfies the search specification (segspec). Returned to user. Passed by reference always.
Returns
flag

DETAILS

No additional details. See Begin_Segment_Search()

◆ Show_Segment_Count()

void Show_Segment_Count ( int *  count)

Finds out how many segments will be returned. This is useful for determining the size of a data structure needed to store incoming items.

Parameters
count- Number of segments that satisfy the search specification. Returned to user. Passed by reference always.

DETAILS

No additional details. See Begin_Segment_Search()