0029116: [Regression] OCAF attributes insertion order is violated again
[occt.git] / src / TDF / TDF_Label.hxx
CommitLineData
42cf5bc1 1// Created on: 1997-02-04
2// Created by: DAUTRY Philippe
3// Copyright (c) 1997-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#ifndef _TDF_Label_HeaderFile
18#define _TDF_Label_HeaderFile
19
20#include <Standard.hxx>
21#include <Standard_DefineAlloc.hxx>
22#include <Standard_Handle.hxx>
23
24#include <TDF_LabelNodePtr.hxx>
25#include <Standard_Integer.hxx>
26#include <Standard_Boolean.hxx>
27#include <Standard_OStream.hxx>
28#include <TDF_AttributeIndexedMap.hxx>
29class Standard_DomainError;
30class Standard_OutOfRange;
31class Standard_NullObject;
32class TDF_ChildIterator;
33class TDF_Attribute;
34class TDF_AttributeIterator;
35class TDF_Data;
36class TDF_LabelMapHasher;
37class Standard_GUID;
38class TDF_IDFilter;
39
40
41//! This class provides basic operations to define
42//! a label in a data structure.
43//! A label is a feature in the feature hierarchy. A
44//! label is always connected to a Data from TDF.
45//! To a label is attached attributes containing the
46//! software components information.
47//!
48//! Label information:
49//!
50//! It is possible to know the tag, the father, the
51//! depth in the tree of the label, if the label is
52//! root, null or equal to another label.
53//!
54//! Comfort methods:
55//! Some methods useful on a label.
56//!
57//! Attributes:
58//!
59//! It is possible to get an attribute in accordance
60//! to an ID, or the yougest previous version of a
61//! current attribute.
62class TDF_Label
63{
64public:
65
66 DEFINE_STANDARD_ALLOC
67
68
69 //! Constructs an empty label object.
70 TDF_Label();
71
72 //! Nullifies the label.
73 void Nullify();
74
75 //! Returns the Data owning <me>.
76 Handle(TDF_Data) Data() const;
77
78 //! Returns the tag of the label.
79 //! This is the integer assigned randomly to a label
80 //! in a data framework. This integer is used to
81 //! identify this label in an entry.
82 Standard_Integer Tag() const;
83
84 //! Returns the label father. This label may be null
85 //! if the label is root.
86 const TDF_Label Father() const;
87
88 //! Returns True if the <aLabel> is null, i.e. it has
89 //! not been included in the data framework.
90 Standard_Boolean IsNull() const;
91
92 //! Sets or unsets <me> and all its descendants as
93 //! imported label, according to <aStatus>.
94 Standard_EXPORT void Imported (const Standard_Boolean aStatus) const;
95
96 //! Returns True if the <aLabel> is imported.
97 Standard_Boolean IsImported() const;
98
99 //! Returns True if the <aLabel> is equal to me (same
100 //! LabelNode*).
101 Standard_Boolean IsEqual (const TDF_Label& aLabel) const;
102 Standard_Boolean operator == (const TDF_Label& aLabel) const
103{
104 return IsEqual(aLabel);
105}
106
107 Standard_Boolean IsDifferent (const TDF_Label& aLabel) const;
108 Standard_Boolean operator != (const TDF_Label& aLabel) const
109{
110 return IsDifferent(aLabel);
111}
112
113 Standard_Boolean IsRoot() const;
114
115 //! Returns true if <me> owns an attribute with <anID> as ID.
116 Standard_EXPORT Standard_Boolean IsAttribute (const Standard_GUID& anID) const;
117
118 //! Adds an Attribute to the current label. Raises if
119 //! there is already one.
bd6f0d2f 120 Standard_EXPORT void AddAttribute (const Handle(TDF_Attribute)& anAttribute, const Standard_Boolean append = Standard_True) const;
42cf5bc1 121
122 //! Forgets an Attribute from the current label,
123 //! setting its forgotten status true and its valid
124 //! status false. Raises if the attribute is not in
125 //! the structure.
126 Standard_EXPORT void ForgetAttribute (const Handle(TDF_Attribute)& anAttribute) const;
127
128 //! Forgets the Attribute of GUID <aguid> from the
129 //! current label . If the attribute doesn't exist
130 //! returns False. Otherwise returns True.
131 Standard_EXPORT Standard_Boolean ForgetAttribute (const Standard_GUID& aguid) const;
132
133 //! Forgets all the attributes. Does it on also on the
134 //! sub-labels if <clearChildren> is set to true. Of
135 //! course, this method is compatible with Transaction
136 //! & Delta mecanisms.
137 Standard_EXPORT void ForgetAllAttributes (const Standard_Boolean clearChildren = Standard_True) const;
138
139 //! Undo Forget action, setting its forgotten status
140 //! false and its valid status true. Raises if the
141 //! attribute is not in the structure.
142 Standard_EXPORT void ResumeAttribute (const Handle(TDF_Attribute)& anAttribute) const;
143
144 //! Finds an attribute of the current label, according
145 //! to <anID>.
146 //! If anAttribute is not a valid one, false is returned.
147 //!
148 //! The method returns True if found, False otherwise.
149 //!
150 //! A removed attribute cannot be found.
151 Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, Handle(TDF_Attribute)& anAttribute) const;
152
aa00364d 153 //! Safe variant of FindAttribute() for arbitrary type of argument
154 template <class T>
155 Standard_Boolean FindAttribute (const Standard_GUID& theID, Handle(T)& theAttr) const
156 {
157 Handle(TDF_Attribute) anAttr = theAttr;
158 return FindAttribute (theID, anAttr) && ! (theAttr = Handle(T)::DownCast(anAttr)).IsNull();
159 }
160
42cf5bc1 161 //! Finds an attribute of the current label, according
162 //! to <anID> and <aTransaction>. This attribute
163 //! has/had to be a valid one for the given
164 //! transaction index . So, this attribute is not
165 //! necessary a valid one.
166 //!
167 //! The method returns True if found, False otherwise.
168 //!
169 //! A removed attribute cannot be found nor a backuped
170 //! attribute of a removed one.
171 Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, const Standard_Integer aTransaction, Handle(TDF_Attribute)& anAttribute) const;
172
173 //! Returns true if <me> or a DESCENDANT of <me> owns
174 //! attributes not yet available in transaction 0. It
175 //! means at least one of their attributes is new,
176 //! modified or deleted.
177 Standard_Boolean MayBeModified() const;
178
179 //! Returns true if <me> owns attributes not yet
180 //! available in transaction 0. It means at least one
181 //! attribute is new, modified or deleted.
182 Standard_Boolean AttributesModified() const;
183
184 //! Returns true if this label has at least one attribute.
185 Standard_EXPORT Standard_Boolean HasAttribute() const;
186
187 //! Returns the number of attributes.
188 Standard_EXPORT Standard_Integer NbAttributes() const;
189
190 //! Returns the depth of the label in the data framework.
191 //! This corresponds to the number of fathers which
192 //! this label has, and is used in determining
193 //! whether a label is root, null or equivalent to another label.
194 //! Exceptions:
195 //! Standard_NullObject if this label is null. This is
196 //! because a null object can have no depth.
197 Standard_EXPORT Standard_Integer Depth() const;
198
199 //! Returns True if <me> is a descendant of
200 //! <aLabel>. Attention: every label is its own
201 //! descendant.
202 Standard_EXPORT Standard_Boolean IsDescendant (const TDF_Label& aLabel) const;
203
204 //! Returns the root label Root of the data structure.
205 //! This has a depth of 0.
206 //! Exceptions:
207 //! Standard_NullObject if this label is null. This is
208 //! because a null object can have no depth.
209 Standard_EXPORT const TDF_Label Root() const;
210
211 //! Returns true if this label has at least one child.
212 Standard_Boolean HasChild() const;
213
214 //! Returns the number of children.
215 Standard_EXPORT Standard_Integer NbChildren() const;
216
217 //! Finds a child label having <aTag> as tag. Creates
218 //! The tag aTag identifies the label which will be the parent.
219 //! If create is true and no child label is found, a new one is created.
220 //! Example:
221 //! //creating a label with tag 10 at Root
222 //! TDF_Label lab1 = aDF->Root().FindChild(10);
223 //! //creating labels 7 and 2 on label 10
224 //! TDF_Label lab2 = lab1.FindChild(7);
225 //! TDF_Label lab3 = lab1.FindChild(2);
226 Standard_EXPORT TDF_Label FindChild (const Standard_Integer aTag, const Standard_Boolean create = Standard_True) const;
227
228 //! Create a new child label of me using autoamtic
229 //! delivery tags provided by TagSource.
230 TDF_Label NewChild() const;
231
232 //! Returns the current transaction index.
233 Standard_EXPORT Standard_Integer Transaction() const;
234
235 //! Returns true if node address of <me> is lower than
236 //! <otherLabel> one. Used to quickly sort labels (not
237 //! on entry criterion).
238 //!
239 //! -C++: inline
240 Standard_EXPORT Standard_Boolean HasLowerNode (const TDF_Label& otherLabel) const;
241
242 //! Returns true if node address of <me> is greater
243 //! than <otherLabel> one. Used to quickly sort labels
244 //! (not on entry criterion).
245 //!
246 //! -C++: inline
247 Standard_EXPORT Standard_Boolean HasGreaterNode (const TDF_Label& otherLabel) const;
248
249 //! Dumps the minimum information about <me> on
250 //! <aStream>.
251 Standard_EXPORT Standard_OStream& Dump (Standard_OStream& anOS) const;
252Standard_OStream& operator<< (Standard_OStream& anOS) const
253{
254 return Dump(anOS);
255}
256
257 //! Dumps the label on <aStream> and its attributes
258 //! rank in <aMap> if their IDs are kept by <IDFilter>.
259 Standard_EXPORT void ExtendedDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap) const;
260
261 //! Dumps the label entry.
262 Standard_EXPORT void EntryDump (Standard_OStream& anOS) const;
263
264
265friend class TDF_ChildIterator;
266friend class TDF_Attribute;
267friend class TDF_AttributeIterator;
268friend class TDF_Data;
269friend class TDF_LabelMapHasher;
270
271
272protected:
273
274
275
276
277
278private:
279
280
281 //! Reserved to the friends.
282 TDF_Label(const TDF_LabelNodePtr& aNode);
283
284 //! Adds an Attribute to <toNode>. Raises if there is
285 //! already one.
0f3d1d7c 286 Standard_EXPORT void AddToNode (const TDF_LabelNodePtr& toNode, const Handle(TDF_Attribute)& anAttribute, const Standard_Boolean append) const;
42cf5bc1 287
288 //! Forgets an Attribute from <fromNode>. Raises if
289 //! the attribute is not in the structure.
290 Standard_EXPORT void ForgetFromNode (const TDF_LabelNodePtr& fromNode, const Handle(TDF_Attribute)& anAttribute) const;
291
292 //! Resumes a forgotten Attribute to <toNode>. Raises
293 //! if the attribute is not in the structure.
294 Standard_EXPORT void ResumeToNode (const TDF_LabelNodePtr& fromNode, const Handle(TDF_Attribute)& anAttribute) const;
295
296 Standard_EXPORT TDF_LabelNodePtr FindOrAddChild (const Standard_Integer aTag, const Standard_Boolean create) const;
297
298 Standard_EXPORT void InternalDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap, const Standard_Boolean extended) const;
299
300
301 TDF_LabelNodePtr myLabelNode;
302
303
304};
305
306
307#include <TDF_Label.lxx>
308
309
310
311
312
313#endif // _TDF_Label_HeaderFile