1 // Copyright (c) 1997-1999 Matra Datavision
2 // Copyright (c) 1999-2014 OPEN CASCADE SAS
4 // This file is part of Open CASCADE Technology software library.
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.
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
15 #ifndef _math_Vector_HeaderFile
16 #define _math_Vector_HeaderFile
18 #include <NCollection_Array1.hxx>
19 #include <NCollection_LocalArray.hxx>
23 // resolve name collisions with X11 headers
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.
34 //! math_Vector V1(-3, 5); // a vector with range [-3..5]
37 //! Vector are copied through assignement :
39 //! math_Vector V2( 1, 9);
42 //! V1(1) = 2.0; // the vector V2 will not be modified.
45 //! The Exception RangeError is raised when trying to access outside
46 //! the range of a vector :
48 //! V1(11) = 0.0 // --> will raise RangeError;
51 //! The Exception DimensionError is raised when the dimensions of two
52 //! vectors are not compatible :
54 //! math_Vector V3(1, 2);
55 //! V3 = V1; // --> will raise DimensionError;
56 //! V1.Add(V3) // --> will raise DimensionError;
64 //! Contructs 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);
68 //! Contructs 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);
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);
76 //! Constructor for converting gp_XY to math_Vector
77 Standard_EXPORT math_Vector(const gp_XY& Other);
79 //! Constructor for converting gp_XYZ to math_Vector
80 Standard_EXPORT math_Vector(const gp_XYZ& Other);
82 //! Initialize all the elements of a vector with "theInitialValue".
83 Standard_EXPORT void Init(const Standard_Real theInitialValue);
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);
89 //! Returns the length of a vector
90 inline Standard_Integer Length() const
92 return Array.Length();
95 //! Returns the value of the theLower index of a vector.
96 inline Standard_Integer Lower() const
101 //! Returns the value of the theUpper index of a vector.
102 inline Standard_Integer Upper() const
104 return Array.Upper();
107 //! Returns the value or the square of the norm of this vector.
108 Standard_EXPORT Standard_Real Norm() const;
110 //! Returns the value of the square of the norm of a vector.
111 Standard_EXPORT Standard_Real Norm2() const;
113 //! Returns the value of the "Index" of the maximum element of a vector.
114 Standard_EXPORT Standard_Integer Max() const;
116 //! Returns the value of the "Index" of the minimum element of a vector.
117 Standard_EXPORT Standard_Integer Min() const;
119 //! Normalizes this vector (the norm of the result
120 //! is equal to 1.0) and assigns the result to this vector
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();
126 //! Normalizes this vector (the norm of the result
127 //! is equal to 1.0) and creates a new vector
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;
133 //! Inverts this vector and assigns the result to this vector.
134 Standard_EXPORT void Invert();
136 //! Inverts this vector and creates a new vector.
137 Standard_EXPORT math_Vector Inverse() const;
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);
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;
151 //! returns the product of a vector and a real value.
152 Standard_EXPORT void Multiply(const Standard_Real theRight);
154 void operator *=(const Standard_Real theRight)
159 //! returns the product of a vector and a real value.
160 Standard_NODISCARD Standard_EXPORT math_Vector Multiplied(const Standard_Real theRight) const;
162 Standard_NODISCARD math_Vector operator*(const Standard_Real theRight) const
164 return Multiplied(theRight);
167 //! returns the product of a vector and a real value.
168 Standard_NODISCARD Standard_EXPORT math_Vector TMultiplied(const Standard_Real theRight) const;
170 friend inline math_Vector operator* (const Standard_Real theLeft, const math_Vector& theRight)
172 return theRight.Multiplied(theLeft);
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);
179 void operator /=(const Standard_Real theRight)
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;
188 Standard_NODISCARD math_Vector operator/(const Standard_Real theRight) const
190 return Divided(theRight);
193 //! adds the vector "theRight" to a vector.
194 //! An exception is raised if the vectors have not the same length.
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);
200 void operator +=(const math_Vector& theRight)
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;
210 Standard_NODISCARD math_Vector operator+(const math_Vector& theRight) const
212 return Added(theRight);
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);
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);
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);
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);
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);
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.
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);
245 //! accesses the value of index "theNum" of a vector.
246 const Standard_Real& Value (const Standard_Integer theNum) const
248 return Array(theNum);
251 //! accesses (in read or write mode) the value of index "theNum" of a vector.
252 inline Standard_Real& Value (const Standard_Integer theNum)
254 return Array(theNum);
257 const Standard_Real& operator()(const Standard_Integer theNum) const
259 return Value(theNum);
262 Standard_Real& operator()(const Standard_Integer theNum)
264 return Value(theNum);
267 //! Initialises a vector by copying "theOther".
268 //! An exception is raised if the Lengths are differents.
269 Standard_EXPORT math_Vector& Initialized(const math_Vector& theOther);
271 math_Vector& operator=(const math_Vector& theOther)
273 return Initialized(theOther);
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
281 return Multiplied(theRight);
284 //! returns the product of a vector by a matrix.
285 Standard_NODISCARD Standard_EXPORT math_Vector Multiplied(const math_Matrix& theRight) const;
287 Standard_NODISCARD math_Vector operator*(const math_Matrix& theRight) const
289 return Multiplied(theRight);
292 //! returns the opposite of a vector.
293 Standard_EXPORT math_Vector Opposite();
295 math_Vector operator-()
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);
304 void operator-=(const math_Vector& theRight)
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;
313 Standard_NODISCARD math_Vector operator-(const math_Vector& theRight) const
315 return Subtracted(theRight);
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);
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;
326 friend inline Standard_OStream& operator<<(Standard_OStream& theO, const math_Vector& theVec)
332 friend class math_Matrix;
336 //! Is used internally to set the "theLower" value of the vector.
337 void SetLower(const Standard_Integer theLower);
341 NCollection_LocalArray<Standard_Real, 512> myLocArray;
342 NCollection_Array1<Standard_Real> Array;