0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / TopLoc / TopLoc_Location.hxx
1 // Created on: 1990-12-19
2 // Created by: Christophe MARION
3 // Copyright (c) 1990-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 _TopLoc_Location_HeaderFile
18 #define _TopLoc_Location_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <TopLoc_SListOfItemLocation.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Standard_Integer.hxx>
27 #include <Standard_OStream.hxx>
28 class Standard_NoSuchObject;
29 class Standard_ConstructionError;
30 class gp_Trsf;
31 class TopLoc_Datum3D;
32
33
34 //! A Location is a composite transition. It comprises a
35 //! series of elementary reference coordinates, i.e.
36 //! objects of type TopLoc_Datum3D, and the powers to
37 //! which these objects are raised.
38 class TopLoc_Location 
39 {
40 public:
41
42   DEFINE_STANDARD_ALLOC
43
44   
45   //! Constructs an empty local coordinate system object.
46   //! Note: A Location constructed from a default datum is said to be "empty".
47   Standard_EXPORT TopLoc_Location();
48   
49   //! Constructs the local coordinate system object defined
50   //! by the transformation T. T invokes in turn, a TopLoc_Datum3D object.
51   Standard_EXPORT TopLoc_Location(const gp_Trsf& T);
52   
53   //! Constructs the local coordinate system object defined by the 3D datum D.
54   //! Exceptions
55   //! Standard_ConstructionError if the transformation
56   //! T does not represent a 3D coordinate system.
57   Standard_EXPORT TopLoc_Location(const Handle(TopLoc_Datum3D)& D);
58   
59   //! Returns true if this location is equal to the Identity transformation.
60     Standard_Boolean IsIdentity() const;
61   
62   //! Resets this location to the Identity transformation.
63     void Identity();
64   
65   //! Returns    the  first   elementary  datum  of  the
66   //! Location.  Use the NextLocation function recursively to access
67   //! the other data comprising this location.
68   //! Exceptions
69   //! Standard_NoSuchObject if this location is empty.
70     const Handle(TopLoc_Datum3D)& FirstDatum() const;
71   
72   //! Returns   the  power  elevation  of    the   first
73   //! elementary datum.
74   //! Exceptions
75   //! Standard_NoSuchObject if this location is empty.
76     Standard_Integer FirstPower() const;
77   
78   //! Returns  a Location representing  <me> without the
79   //! first datum. We have the relation :
80   //!
81   //! <me> = NextLocation() * FirstDatum() ^ FirstPower()
82   //! Exceptions
83   //! Standard_NoSuchObject if this location is empty.
84     const TopLoc_Location& NextLocation() const;
85   
86   //! Returns  the transformation    associated  to  the
87   //! coordinate system.
88   Standard_EXPORT const gp_Trsf& Transformation() const;
89 Standard_EXPORT operator gp_Trsf() const;
90   
91   //! Returns the inverse of <me>.
92   //!
93   //! <me> * Inverted() is an Identity.
94   Standard_NODISCARD Standard_EXPORT TopLoc_Location Inverted() const;
95   
96   //! Returns <me> * <Other>, the  elementary datums are
97   //! concatenated.
98   Standard_NODISCARD Standard_EXPORT TopLoc_Location Multiplied (const TopLoc_Location& Other) const;
99 Standard_NODISCARD TopLoc_Location operator* (const TopLoc_Location& Other) const
100 {
101   return Multiplied(Other);
102 }
103   
104   //! Returns  <me> / <Other>.
105   Standard_NODISCARD Standard_EXPORT TopLoc_Location Divided (const TopLoc_Location& Other) const;
106 Standard_NODISCARD TopLoc_Location operator/ (const TopLoc_Location& Other) const
107 {
108   return Divided(Other);
109 }
110   
111   //! Returns <Other>.Inverted() * <me>.
112   Standard_NODISCARD Standard_EXPORT TopLoc_Location Predivided (const TopLoc_Location& Other) const;
113   
114   //! Returns me at the power <pwr>.   If <pwr>  is zero
115   //! returns  Identity.  <pwr> can  be lower  than zero
116   //! (usual meaning for powers).
117   Standard_NODISCARD Standard_EXPORT TopLoc_Location Powered (const Standard_Integer pwr) const;
118
119   //! Returns a hashed value for this local coordinate system. This value is used, with map tables, to store and
120   //! retrieve the object easily, and is in the range [1, theUpperBound].
121   //! @param theUpperBound the upper bound of the range a computing hash code must be within
122   //! @return a computed hash code, in the range [1, theUpperBound]
123   Standard_EXPORT Standard_Integer HashCode (Standard_Integer theUpperBound) const;
124   
125   //! Returns true if this location and the location Other
126   //! have the same elementary data, i.e. contain the same
127   //! series of TopLoc_Datum3D and respective powers.
128   //! This method is an alias for operator ==.
129   Standard_EXPORT Standard_Boolean IsEqual (const TopLoc_Location& Other) const;
130 Standard_Boolean operator == (const TopLoc_Location& Other) const
131 {
132   return IsEqual(Other);
133 }
134   
135   //! Returns true if this location and the location Other do
136   //! not have the same elementary data, i.e. do not
137   //! contain the same series of TopLoc_Datum3D and respective powers.
138   //! This method is an alias for operator !=.
139   Standard_EXPORT Standard_Boolean IsDifferent (const TopLoc_Location& Other) const;
140 Standard_Boolean operator != (const TopLoc_Location& Other) const
141 {
142   return IsDifferent(Other);
143 }
144   
145   //! Dumps the content of me into the stream
146   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
147
148   //! Prints the contents of <me> on the stream <s>.
149   Standard_EXPORT void ShallowDump (Standard_OStream& S) const;
150
151
152
153
154 protected:
155
156
157
158
159
160 private:
161
162
163
164   TopLoc_SListOfItemLocation myItems;
165
166
167 };
168
169
170 #include <TopLoc_Location.lxx>
171
172
173 //! Computes a hash code for the given location, in the range [1, theUpperBound]
174 //! @param theLocation the location which hash code is to be computed
175 //! @param theUpperBound the upper bound of the range a computing hash code must be within
176 //! @return a computed hash code, in the range [1, theUpperBound]
177 inline Standard_Integer HashCode (const TopLoc_Location& theLocation, const Standard_Integer theUpperBound)
178 {
179   return theLocation.HashCode (theUpperBound);
180 }
181
182 inline void ShallowDump(const TopLoc_Location& me,Standard_OStream& S) {
183  me.ShallowDump(S);
184 }
185
186
187
188 #endif // _TopLoc_Location_HeaderFile