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