0024624: Lost word in license statement in source files
[occt.git] / src / TopExp / TopExp_Explorer.cdl
1 -- Created on: 1993-01-14
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 class Explorer from TopExp 
18
19         ---Purpose: An Explorer is a Tool to visit  a Topological Data
20         --          Structure form the TopoDS package.
21         --          
22         --          An Explorer is built with :
23         --          
24         --            * The Shape to explore.
25         --            
26         --            * The type of Shapes to find : e.g VERTEX, EDGE.
27         --            This type cannot be SHAPE.
28         --            
29         --            * The type of Shapes to avoid. e.g  SHELL, EDGE.
30         --            By default   this type is  SHAPE which  means no
31         --            restriction on the exploration.
32         --            
33         --            
34         --          The Explorer  visits  all the  structure   to find
35         --          shapes of the   requested  type  which   are   not
36         --          contained in the type to avoid.
37         --          
38         --          Example to find all the Faces in the Shape S :
39         --          
40         --          TopExp_Explorer Ex;
41         --          for (Ex.Init(S,TopAbs_FACE); Ex.More(); Ex.Next()) {
42         --            ProcessFace(Ex.Current());
43         --            }
44         --            
45         --          // an other way
46         --          TopExp_Explorer Ex(S,TopAbs_FACE);
47         --          while (Ex.More()) {
48         --            ProcessFace(Ex.Current());
49         --            Ex.Next();
50         --            }
51         --            
52         --          To find all the vertices which are not in an edge :
53         --          
54         --          for (Ex.Init(S,TopAbs_VERTEX,TopAbs_EDGE); ...)
55         --          
56         --          
57         --          To  find all the faces  in   a SHELL, then all the
58         --          faces not in a SHELL :
59         --          
60         --          TopExp_Explorer Ex1, Ex2;
61         --          
62         --          for (Ex1.Init(S,TopAbs_SHELL),...) {
63         --            // visit all shells
64         --            for (Ex2.Init(Ex1.Current(),TopAbs_FACE),...) {
65         --              // visit all the faces of the current shell
66         --              }
67         --            }
68         --            
69         --          for (Ex1.Init(S,TopAbs_FACE,TopAbs_SHELL),...) {
70         --            // visit all faces not in a shell
71         --            }
72         --          
73         --          
74         --          If   the type  to avoid  is   the same  or is less
75         --          complex than the type to find it has no effect.
76         --          
77         --          For example searching edges  not in a vertex  does
78         --          not make a difference.
79         --          
80
81 uses
82     ShapeEnum       from TopAbs,
83     Shape           from TopoDS,
84     Stack           from TopExp
85     
86 raises
87     NoMoreObject from Standard,
88     NoSuchObject from Standard
89
90 is
91
92     Create returns Explorer from TopExp;
93         ---Purpose: Creates an empty explorer, becomes usefull after Init.
94     
95     Create(S       : Shape     from TopoDS;
96            ToFind  : ShapeEnum from TopAbs;
97            ToAvoid : ShapeEnum from TopAbs = TopAbs_SHAPE)
98     returns Explorer from TopExp;
99         ---Purpose: Creates an Explorer on the Shape <S>. 
100         --          
101         --          <ToFind> is the type of shapes to search. 
102         --              TopAbs_VERTEX, TopAbs_EDGE, ...
103         --           
104         --          <ToAvoid>   is the type   of shape to  skip in the
105         --          exploration.   If   <ToAvoid>  is  equal  or  less
106         --          complex than <ToFind> or if  <ToAVoid> is SHAPE it
107         --          has no effect on the exploration.
108         --          
109         
110     Init(me : in out; S       : Shape       from TopoDS;
111                       ToFind  : ShapeEnum from TopAbs;
112                       ToAvoid : ShapeEnum from TopAbs = TopAbs_SHAPE)
113         ---Purpose: Resets this explorer on the shape S. It is initialized to
114 -- search the shape S, for shapes of type ToFind, that
115 -- are not part of a shape ToAvoid.
116 -- If the shape ToAvoid is equal to TopAbs_SHAPE, or
117 -- if it is the same as, or less complex than, the shape
118 -- ToFind it has no effect on the search.          
119     is static;
120     
121     More(me) returns Boolean
122         ---Purpose: Returns  True if  there are   more  shapes in  the
123         --          exploration. 
124         ---C++: inline
125    is static;
126         
127     Next(me : in out)
128         ---Purpose: Moves to the next Shape in the exploration.
129 -- Exceptions
130 -- Standard_NoMoreObject if there are no more shapes to explore.
131     raises
132         NoMoreObject 
133     is static;
134     
135     Current(me) returns Shape from TopoDS
136         ---Purpose: Returns the current shape in the exploration.
137  -- Exceptions
138 -- Standard_NoSuchObject if this explorer has no more shapes to explore.
139     raises NoSuchObject from Standard 
140     ---C++: return const &
141     is static;
142     
143     ReInit(me : in out)
144         ---Purpose: Reinitialize  the    exploration with the original
145         --          arguments.
146     is static;
147     
148     Depth(me) returns Integer
149         ---Purpose: Returns the current depth of the exploration. 0 is
150         --          the shape to explore itself.
151         ---C++: inline
152         is static;
153     
154     Clear(me : in out)
155         ---Purpose: Clears the content of the explorer. It will return
156         --          False on More().
157         ---C++: inline
158     is static;
159     
160     -- private implementation methods
161
162     Destroy(me : in out);
163     ---C++: alias ~
164     
165 fields
166     myStack       : Stack           from TopExp;
167     myTop         : Integer         from Standard;
168     mySizeOfStack : Integer         from Standard;
169     myShape       : Shape           from TopoDS;
170     hasMore       : Boolean         from Standard;
171     toFind        : ShapeEnum       from TopAbs;
172     toAvoid       : ShapeEnum       from TopAbs;
173     
174 end Explorer;