0024624: Lost word in license statement in source files
[occt.git] / src / TopExp / TopExp_Explorer.cdl
CommitLineData
b311480e 1-- Created on: 1993-01-14
2-- Created by: Remi LEQUETTE
3-- Copyright (c) 1993-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 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
973c2be1 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.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
17class 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
81uses
82 ShapeEnum from TopAbs,
83 Shape from TopoDS,
84 Stack from TopExp
85
86raises
87 NoMoreObject from Standard,
88 NoSuchObject from Standard
89
90is
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
165fields
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
174end Explorer;