0028838: Configuration - undefine macros coming from X11 headers in place of collision
[occt.git] / src / math / math_Vector.hxx
1 // Copyright (c) 1997-1999 Matra Datavision
2 // Copyright (c) 1999-2014 OPEN CASCADE SAS
3 //
4 // This file is part of Open CASCADE Technology software library.
5 //
6 // This library is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU Lesser General Public License version 2.1 as published
8 // by the Free Software Foundation, with special exception defined in the file
9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 // distribution for complete text of the license and disclaimer of any warranty.
11 //
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
14
15 #ifndef _math_Vector_HeaderFile
16 #define _math_Vector_HeaderFile
17
18 #include <math_SingleTab.hxx>
19 #include <gp_XY.hxx>
20 #include <gp_XYZ.hxx>
21
22 // resolve name collisions with X11 headers
23 #ifdef Opposite
24   #undef Opposite
25 #endif
26
27 class math_Matrix;
28
29 //! This class implements the real vector abstract data type.
30 //! Vectors can have an arbitrary range which must be defined at
31 //! the declaration and cannot be changed after this declaration.
32 //! @code
33 //!    math_Vector V1(-3, 5); // a vector with range [-3..5]
34 //! @endcode
35 //!
36 //! Vector are copied through assignement :
37 //! @code
38 //!    math_Vector V2( 1, 9);
39 //!    ....
40 //!    V2 = V1;
41 //!    V1(1) = 2.0; // the vector V2 will not be modified.
42 //! @endcode
43 //!
44 //! The Exception RangeError is raised when trying to access outside
45 //! the range of a vector :
46 //! @code
47 //!    V1(11) = 0.0 // --> will raise RangeError;
48 //! @endcode
49 //!
50 //! The Exception DimensionError is raised when the dimensions of two
51 //! vectors are not compatible :
52 //! @code
53 //!    math_Vector V3(1, 2);
54 //!    V3 = V1;    // --> will raise DimensionError;
55 //!    V1.Add(V3)  // --> will raise DimensionError;
56 //! @endcode
57 class math_Vector
58 {
59 public:
60
61   DEFINE_STANDARD_ALLOC
62
63   //! Contructs a non-initialized vector in the range [theLower..theUpper]
64   //! "theLower" and "theUpper" are the indexes of the lower and upper bounds of the constructed vector.
65   Standard_EXPORT math_Vector(const Standard_Integer theLower, const Standard_Integer theUpper);
66
67   //! Contructs a vector in the range [theLower..theUpper]
68   //! whose values are all initialized with the value "theInitialValue"
69   Standard_EXPORT math_Vector(const Standard_Integer theLower, const Standard_Integer theUpper, const Standard_Real theInitialValue);
70
71   //! Constructs a vector in the range [theLower..theUpper]
72   //! with the "c array" theTab.
73   Standard_EXPORT math_Vector(const Standard_Address theTab, const Standard_Integer theLower, const Standard_Integer theUpper);
74
75   //! Constructor for converting gp_XY to math_Vector
76   Standard_EXPORT math_Vector(const gp_XY& Other);
77   
78   //! Constructor for converting gp_XYZ to math_Vector
79   Standard_EXPORT math_Vector(const gp_XYZ& Other);
80
81   //! Initialize all the elements of a vector with "theInitialValue".
82   Standard_EXPORT void Init(const Standard_Real theInitialValue);
83
84   //! Constructs a copy for initialization.
85   //! An exception is raised if the lengths of the vectors are different.
86   Standard_EXPORT math_Vector(const math_Vector& theOther);
87
88   //! Returns the length of a vector
89   inline Standard_Integer Length() const
90   {
91     return UpperIndex - LowerIndex +1;
92   }
93
94   //! Returns the value of the theLower index of a vector.
95   inline Standard_Integer Lower() const
96   {
97     return LowerIndex;
98   }
99
100   //! Returns the value of the theUpper index of a vector.
101   inline Standard_Integer Upper() const
102   {
103     return UpperIndex;
104   }
105
106   //! Returns the value or the square  of the norm of this vector.
107   Standard_EXPORT Standard_Real Norm() const;
108
109   //! Returns the value of the square of the norm of a vector.
110   Standard_EXPORT Standard_Real Norm2() const;
111
112   //! Returns the value of the "Index" of the maximum element of a vector.
113   Standard_EXPORT Standard_Integer Max() const;
114
115   //! Returns the value of the "Index" of the minimum element  of a vector.
116   Standard_EXPORT Standard_Integer Min() const;
117
118   //! Normalizes this vector (the norm of the result
119   //! is equal to 1.0) and assigns the result to this vector
120   //! Exceptions
121   //! Standard_NullValue if this vector is null (i.e. if its norm is
122   //! less than or equal to Standard_Real::RealEpsilon().
123   Standard_EXPORT void Normalize();
124
125   //! Normalizes this vector (the norm of the result
126   //! is equal to 1.0) and creates a new vector
127   //! Exceptions
128   //! Standard_NullValue if this vector is null (i.e. if its norm is
129   //! less than or equal to Standard_Real::RealEpsilon().
130   Standard_EXPORT math_Vector Normalized() const;
131
132   //! Inverts this vector and assigns the result to this vector.
133   Standard_EXPORT void Invert();
134
135   //! Inverts this vector and creates a new vector.
136   Standard_EXPORT math_Vector Inverse() const;
137
138   //! sets a vector from "theI1" to "theI2" to the vector "theV";
139   //! An exception is raised if "theI1" is less than "LowerIndex" or "theI2" is greater than "UpperIndex" or "theI1" is greater than "theI2".
140   //! An exception is raised if "theI2-theI1+1" is different from the "Length" of "theV".
141   Standard_EXPORT void Set(const Standard_Integer theI1, const Standard_Integer theI2, const math_Vector& theV);
142
143   //!Creates a new vector by inverting the values of this vector
144   //! between indexes "theI1" and "theI2".
145   //! If the values of this vector were (1., 2., 3., 4.,5., 6.),
146   //! by slicing it between indexes 2 and 5 the values
147   //! of the resulting vector are (1., 5., 4., 3., 2., 6.)
148   Standard_EXPORT math_Vector Slice(const Standard_Integer theI1, const Standard_Integer theI2) const;
149
150   //! returns the product of a vector and a real value.
151   Standard_EXPORT void Multiply(const Standard_Real theRight);
152
153   void operator *=(const Standard_Real theRight)
154   {
155     Multiply(theRight);
156   }
157
158   //! returns the product of a vector and a real value.
159   Standard_EXPORT math_Vector Multiplied(const Standard_Real theRight) const;
160
161   math_Vector operator*(const Standard_Real theRight) const
162   {
163     return Multiplied(theRight);
164   }
165
166   //! returns the product of a vector and a real value.
167   Standard_EXPORT math_Vector TMultiplied(const Standard_Real theRight) const;
168
169   friend inline math_Vector operator* (const Standard_Real theLeft, const math_Vector& theRight) 
170   {
171     return theRight.Multiplied(theLeft);
172   }
173
174   //! divides a vector by the value "theRight".
175   //! An exception is raised if "theRight" = 0.
176   Standard_EXPORT void Divide(const Standard_Real theRight);
177
178   void operator /=(const Standard_Real theRight) 
179   {
180     Divide(theRight);
181   }
182
183   //! divides a vector by the value "theRight".
184   //! An exception is raised if "theRight" = 0.
185   Standard_EXPORT math_Vector Divided(const Standard_Real theRight) const;
186
187   math_Vector operator/(const Standard_Real theRight) const
188   {
189     return Divided(theRight);
190   }
191
192   //! adds the vector "theRight" to a vector.
193   //! An exception is raised if the vectors have not the same length.
194   //! Warning
195   //! In order to avoid time-consuming copying of vectors, it
196   //! is preferable to use operator += or the function Add whenever possible.
197   Standard_EXPORT void Add(const math_Vector& theRight);
198
199   void operator +=(const math_Vector& theRight) 
200   {
201     Add(theRight);
202   }
203
204   //! adds the vector theRight to a vector.
205   //! An exception is raised if the vectors have not the same length.
206   //! An exception is raised if the lengths are not equal.
207   Standard_EXPORT math_Vector Added(const math_Vector& theRight) const;
208
209   math_Vector operator+(const math_Vector& theRight) const
210   {
211     return Added(theRight);
212   }
213
214   //! sets a vector to the product of the vector "theLeft"
215   //! with the matrix "theRight".
216   Standard_EXPORT void Multiply(const math_Vector& theLeft, const math_Matrix& theRight);
217
218   //!sets a vector to the product of the matrix "theLeft"
219   //! with the vector "theRight".
220   Standard_EXPORT void Multiply(const math_Matrix& theLeft, const math_Vector& theRight);
221
222   //! sets a vector to the product of the transpose
223   //! of the matrix "theTLeft" by the vector "theRight".
224   Standard_EXPORT void TMultiply(const math_Matrix& theTLeft, const math_Vector& theRight);
225
226   //! sets a vector to the product of the vector
227   //! "theLeft" by the transpose of the matrix "theTRight".
228   Standard_EXPORT void TMultiply(const math_Vector& theLeft, const math_Matrix& theTRight);
229
230   //! sets a vector to the sum of the vector "theLeft"
231   //! and the vector "theRight".
232   //! An exception is raised if the lengths are different.
233   Standard_EXPORT void Add(const math_Vector& theLeft, const math_Vector& theRight);
234
235   //! sets a vector to the Subtraction of the
236   //! vector theRight from the vector theLeft.
237   //! An exception is raised if the vectors have not the same length.
238   //! Warning
239   //! In order to avoid time-consuming copying of vectors, it
240   //! is preferable to use operator -= or the function
241   //! Subtract whenever possible.
242   Standard_EXPORT void Subtract(const math_Vector& theLeft,const math_Vector& theRight);
243
244   //! accesses (in read or write mode) the value of index "theNum" of a vector.
245   inline Standard_Real& Value(const Standard_Integer theNum) const
246   {
247     Standard_RangeError_Raise_if(theNum < LowerIndex || theNum > UpperIndex, " ");
248     return Array(theNum);
249   }
250
251   Standard_Real& operator()(const Standard_Integer theNum) const
252   {
253     return Value(theNum);
254   }
255
256   //! Initialises a vector by copying "theOther".
257   //! An exception is raised if the Lengths are differents.
258   Standard_EXPORT math_Vector& Initialized(const math_Vector& theOther);
259
260   math_Vector& operator=(const math_Vector& theOther)
261   {
262     return Initialized(theOther);
263   }
264
265   //! returns the inner product of 2 vectors.
266   //! An exception is raised if the lengths are not equal.
267   Standard_EXPORT Standard_Real Multiplied(const math_Vector& theRight) const;
268   Standard_Real operator*(const math_Vector& theRight) const
269   {
270     return Multiplied(theRight);
271   }
272
273   //! returns the product of a vector by a matrix.
274   Standard_EXPORT math_Vector Multiplied(const math_Matrix& theRight) const;
275
276   math_Vector operator*(const math_Matrix& theRight) const
277   {
278     return Multiplied(theRight);
279   }
280
281   //! returns the opposite of a vector.
282   Standard_EXPORT math_Vector Opposite();
283
284   math_Vector operator-()
285   {
286     return Opposite();
287   }
288
289   //! returns the subtraction of "theRight" from "me".
290   //! An exception is raised if the vectors have not the same length.
291   Standard_EXPORT void Subtract(const math_Vector& theRight);
292
293   void operator-=(const math_Vector& theRight)
294   {
295     Subtract(theRight);
296   }
297
298   //! returns the subtraction of "theRight" from "me".
299   //! An exception is raised if the vectors have not the same length.
300   Standard_EXPORT math_Vector Subtracted(const math_Vector& theRight) const;
301
302   math_Vector operator-(const math_Vector& theRight) const
303   {
304     return Subtracted(theRight);
305   }
306
307   //! returns the multiplication of a real by a vector.
308   //! "me" = "theLeft" * "theRight"
309   Standard_EXPORT void Multiply(const Standard_Real theLeft,const math_Vector& theRight);
310
311   //! Prints information on the current state of the object.
312   //! Is used to redefine the operator <<.
313   Standard_EXPORT void Dump(Standard_OStream& theO) const;
314
315   friend inline Standard_OStream& operator<<(Standard_OStream& theO, const math_Vector& theVec)
316   {
317     theVec.Dump(theO);
318     return theO;
319   }
320
321   friend class math_Matrix;
322
323 protected:
324
325   //! Is used internally to set the "theLower" value of the vector.
326   void SetLower(const Standard_Integer theLower);
327
328 private:
329
330   Standard_Integer LowerIndex;
331   Standard_Integer UpperIndex;
332   math_SingleTab<Standard_Real> Array;
333 };
334
335 #endif