inc/FBaseDoubleMatrix.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FBaseDoubleMatrix.h
  20  * @brief       This is the header file for the %DoubleMatrix class.
  21  *
  22  * This header file contains the declarations of the %DoubleMatrix class.
  23  *
  24  */
  25
  26 #ifndef _FBASE_DOUBLE_MATRIX_H_
  27 #define _FBASE_DOUBLE_MATRIX_H_
  28
  29 #include <FBase.h>
  30 #include <FBaseTypes.h>
  31 #include <FBaseObject.h>
  32
  33 namespace Tizen { namespace Base
  34 {
  35 /**
  36  * @class       DoubleMatrix
  37  * @brief       This class encapsulates a two-dimensional matrix.
  38  *
  39  * @since 2.0
  40  *
  41  * The %DoubleMatrix class provides a @c double precision, two-dimensional matrix class.
  42  *
  43  */
  44 class _OSP_EXPORT_ DoubleMatrix
  45         : public Tizen::Base::Object
  46 {
  47 public:
  48         /**
  49          * Copying of objects using this copy constructor is allowed.
  50          *
  51          * @since 2.0
  52          *
  53          * @param[in]   rhs     An instance of %DoubleMatrix
  54          */
  55         DoubleMatrix(const DoubleMatrix& rhs);
  56
  57         /**
  58          * Constructs a row by column null matrix in which all elements are zero.
  59          *
  60          * @since 2.0
  61          *
  62          * @param[in]   rowCount        The number of rows in the current instance
  63          * @param[in]   columnCount     The number of columns in the current instance
  64          */
  65         DoubleMatrix(int rowCount, int columnCount);
  66
  67         /**
  68          * Constructs a row by column matrix initialized to the values in the specified array.
  69          *
  70          * @since 2.0
  71          *
  72          * @param[in]   rowCount        The number of rows in the current instance
  73          * @param[in]   columnCount     The number of columns in the current instance
  74          * @param[in]   pArray  A one-dimensional array @n The array must be at least row * column in length.
  75          * @param[in]   rowMajor        Set to @c true to copy the array in row-major order, @n
  76          *                                                      else @c copy in column-major order
  77          */
  78         DoubleMatrix(int rowCount, int columnCount, const double* pArray, bool rowMajor = true);
  79
  80         /**
  81          * Constructs a row by column matrix initialized to the values in the specified array.
  82          *
  83          * @since 2.0
  84          *
  85          * @param[in]   rowCount        The number of rows in the current instance
  86          * @param[in]   columnCount     The number of columns in the current instance
  87          * @param[in]   pArray[]        A two-dimensional array @n The array must be at least row * column in length.
  88          */
  89         DoubleMatrix(int rowCount, int columnCount, const double* pArray[]);
  90
  91         /**
  92          * This destructor overrides Tizen::Base::Object::~Object().
  93          *
  94          * @since 2.0
  95          *
  96          */
  97         virtual ~DoubleMatrix(void);
  98
  99         /**
 100          * Checks whether the current instance and the specified instance of %DoubleMatrix are equal.
 101          *
 102          * @since 2.0
 103          *
 104          * @return      @c true if all matrix members of the current instance are equal to the corresponding matrix members in the specified instance, @n
 105          *                      else @c false
 106          * @param[in]   rhs     An instance of %DoubleMatrix
 107          */
 108         bool operator ==(const DoubleMatrix& rhs) const;
 109
 110         /**
 111          * Checks whether the current instance and the specified instance of %DoubleMatrix are not equal.
 112          *
 113          * @since 2.0
 114          *
 115          * @return      @c true if all matrix members of the current instance are not equal to the corresponding matrix members in the specified instance, @n
 116          *                      else @c false
 117          * @param[in]   rhs     An instance of %DoubleMatrix
 118          */
 119         bool operator !=(const DoubleMatrix& rhs) const;
 120
 121         /**
 122          * Copying of objects using this copy assignment operator is allowed.
 123          *
 124          * @since 2.0
 125          *
 126          * @return      The reference to this instance
 127          * @param[in]   rhs     An instance of %DoubleMatrix
 128          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 129          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 130          * @remarks     If either row or column count of the current instance is not same with that of the specified instance,
 131          *                              return the reference to this instance without assigning.
 132          */
 133         DoubleMatrix& operator =(const DoubleMatrix& rhs);
 134
 135         /**
 136          * Checks whether the current instance of %DoubleMatrix equals the specified instance of %DoubleMatrix.
 137          *
 138          * @since 2.0
 139          *
 140          * @return      @c true if the values of the current instance are equal to the value of the specified instance, @n
 141          *                      else @c false
 142          * @param[in]   obj     An instance of %DoubleMatrix
 143          * @remarks     This method overrides Tizen::Base::Object::Equals(). This method uses the values of the Matrix components to compare the two instances.
 144          */
 145         virtual bool Equals(const Tizen::Base::Object& obj) const;
 146
 147         /**
 148          * Gets the hash value of the current instance of %DoubleMatrix.
 149          *
 150          * @since 2.0
 151          *
 152          * @return      The hash value of the current instance
 153          * @remarks     Two equal instances must return the same hash value. For better performance,
 154          *                              the used hash function must generate a random distribution for all inputs.
 155          */
 156         virtual int GetHashCode(void) const;
 157
 158         /**
 159          * Adds the value of the specified instance to the current instance of %DoubleMatrix.
 160          *
 161          * @since 2.0
 162          *
 163          * @return              An error code
 164          * @param[in]   matrix  An instance of %DoubleMatrix
 165          * @exception   E_SUCCESS       The method is successful.
 166          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 167          */
 168         result Add(const DoubleMatrix& matrix);
 169
 170         /**
 171          * Adds the value to each matrix members of the current instance of %DoubleMatrix.
 172          *
 173          * @since 2.0
 174          *
 175          * @param[in]   value   A @c double value to add
 176          */
 177         void AddToEachElement(double value);
 178
 179         /**
 180          * Gets the number of column in the current instance of %DoubleMatrix.
 181          *
 182          * @since 2.0
 183          *
 184          * @return      The number of column in the current instance
 185          */
 186         int GetColumnCount(void) const;
 187
 188         /**
 189          * Gets a new array that includes the values of the specified column in the current instance of %DoubleMatrix.
 190          *
 191          * @since 2.0
 192          *
 193          * @return      A pointer to @c double array
 194          * @param[in]   columnIndex     The target column number in the current instance
 195          * @exception   E_INVALID_ARG   The @c columnIndex is larger than the column count of the current instance.
 196          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 197          */
 198         double* GetColumnN(int columnIndex) const;
 199
 200         /**
 201          * Gets the determinant of the current instance of %DoubleMatrix.
 202          *
 203          * @since 2.0
 204          *
 205          * @return      The determinant value of the current instance
 206          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 207          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 208          * @remarks     If the current instance is not a square matrix, return zero.
 209          */
 210         double GetDeterminant(void) const;
 211
 212         /**
 213          * Gets the value at the specified row and column of the current instance of %DoubleMatrix.
 214          *
 215          * @since 2.0
 216          *
 217          * @return      The value at the specified row and column of the current instance
 218          * @param[in]   rowIndex        The target row number in the current instance
 219          * @param[in]   columnIndex     The target column number in the current instance
 220          * @exception   E_INVALID_ARG   The @c columnIndex or @c rowIndex is larger than that of the current instance.
 221          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 222          */
 223         double GetElement(int rowIndex, int columnIndex) const;
 224
 225         /**
 226          * Gets the inverse matrix of the current instance of %DoubleMatrix.
 227          *
 228          * @since 2.0
 229          *
 230          * @return       A pointer to the instance of %DoubleMatrix containing the resulting value of the operation
 231          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 232          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 233          */
 234         DoubleMatrix* GetInverseN(void) const;
 235
 236         /**
 237          * Gets the number of row in the current instance of %DoubleMatrix.
 238          *
 239          * @since 2.0
 240          *
 241          * @return      The number of row in the current instance
 242          */
 243         int GetRowCount(void) const;
 244
 245         /**
 246          * Gets a new array that includes the values of the specified row in the current instance of %DoubleMatrix.
 247          *
 248          * @since 2.0
 249          *
 250          * @return      A pointer to @c double array
 251          * @param[in]   rowIndex        The target row number in the current instance
 252          * @exception   E_INVALID_ARG   The @c rowIndex is larger than the row count of the current instance.
 253          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 254          */
 255         double* GetRowN(int rowIndex) const;
 256
 257         /**
 258          * Gets the trace of the current instance of %DoubleMatrix.
 259          *
 260          * @since 2.0
 261          *
 262          * @return              An error code
 263          * @param[out]  value   A @c double value
 264          * @exception   E_SUCCESS       The method is successful.
 265          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 266          */
 267         result GetTrace(double& value) const;
 268
 269         /**
 270          * Gets the transpose matrix of the current instance of %DoubleMatrix.
 271          *
 272          * @since 2.0
 273          *
 274          * @return       A pointer to the instance of %DoubleMatrix containing the resulting value of the operation
 275          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 276          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 277          */
 278         DoubleMatrix* GetTransposeN(void) const;
 279
 280         /**
 281          * Checks whether the current instance is an identity matrix.
 282          *
 283          * @since 2.0
 284          *
 285          * @return      @c true if the matrix is an identity matrix, @n
 286          *                      else @c false
 287          */
 288         bool IsIdentity(void) const;
 289
 290         /**
 291          * Checks whether the current matrix is invertible.
 292          *
 293          * @since 2.0
 294          *
 295          * @return      @c true if the matrix is invertible, @n
 296          *                      else @c false
 297          */
 298         bool IsInvertible(void) const;
 299
 300         /**
 301          * Multiplies the value of the specified instance with the current instance of %DoubleMatrix.
 302          *
 303          * @since 2.0
 304          *
 305          * @return              An error code
 306          * @param[in]   matrix  An instance of %DoubleMatrix
 307          * @exception   E_SUCCESS       The method is successful.
 308          * @exception   E_INVALID_ARG   The column count of the current instance is not same with the row count of the specified instance.
 309          */
 310         result Multiply(const DoubleMatrix& matrix);
 311
 312         /**
 313          * Multiplies the value with each matrix members of the current instance of %DoubleMatrix.
 314          *
 315          * @since 2.0
 316          *
 317          * @param[in]   value   A @c double value to multiply
 318          */
 319         void Multiply(double value);
 320
 321         /**
 322          * Negates the matrix members of the current instance of %DoubleMatrix.
 323          *
 324          * @since 2.0
 325          */
 326         void Negate(void);
 327
 328         /**
 329          * Sets the value of the current instance of %DoubleMatrix to its identity.
 330          *
 331          * @since 2.0
 332          *
 333          * @return              An error code
 334          * @exception   E_SUCCESS       The method is successful.
 335          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 336          */
 337         result SetAsIdentity(void);
 338
 339         /**
 340          * Sets the value of the current instance of %DoubleMatrix to its inverse.
 341          *
 342          * @since 2.0
 343          *
 344          * @return              An error code
 345          * @exception   E_SUCCESS       The method is successful.
 346          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 347          */
 348         result Invert(void);
 349
 350         /**
 351          * Sets the value of the current instance of %DoubleMatrix to its transpose.
 352          *
 353          * @since 2.0
 354          *
 355          * @return              An error code
 356          * @exception   E_SUCCESS       The method is successful.
 357          * @exception   E_INVALID_OPERATION     The current instance is not a square matrix.
 358          */
 359         result Transpose(void);
 360
 361         /**
 362          * Sets the values of the specified array to the specified column of the current instance of %DoubleMatrix.
 363          *
 364          * @since 2.0
 365          *
 366          * @return              An error code
 367          * @param[in]   columnIndex     The target column number in the current instance
 368          * @param[in]   pArray  An array which includes the values @n The array must be at least row in length.
 369          * @exception   E_SUCCESS       The method is successful.
 370          * @exception   E_INVALID_ARG   The @c pArray is @c null, or the @c columnIndex is larger than the column count of the current instance.
 371          */
 372         result SetColumn(int columnIndex, const double* pArray);
 373
 374         /**
 375          * Sets the values of the specified array to the specified row of the current instance of %DoubleMatrix.
 376          *
 377          * @since 2.0
 378          *
 379          * @return              An error code
 380          * @param[in]   rowIndex        The target row number in the current instance
 381          * @param[in]   pArray  An array which includes the values @n The array must be at least column in length.
 382          * @exception   E_SUCCESS       The method is successful.
 383          * @exception   E_INVALID_ARG   The @c pArray is @c null, or the @c rowIndex is larger than the row count of the current instance.
 384          */
 385         result SetRow(int rowIndex, const double* pArray);
 386
 387         /**
 388          * Sets the value to the specified row and column of the current instance of %DoubleMatrix.
 389          *
 390          * @since 2.0
 391          *
 392          * @return              An error code
 393          * @param[in]   rowIndex        The target row number in the current instance
 394          * @param[in]   columnIndex     The target column number in the current instance
 395          * @param[in]   value   A @c double value
 396          * @exception   E_SUCCESS       The method is successful.
 397          * @exception   E_INVALID_ARG   The pArray is @c null, or the @c rowIndex is larger than the row count of the current instance,
 398          *                              or the @c columnIndex is larger than the column count of the current instance.
 399          */
 400         result SetElement(int rowIndex, int columnIndex, double value);
 401
 402         /**
 403          * Sets the values to the current instance of %DoubleMatrix in either the row-major or column-major order.
 404          *
 405          * @since 2.0
 406          *
 407          * @return              An error code
 408          * @param[in]   pArray  A one-dimensional array @n The array must be at least row * column in length.
 409          * @param[in]   rowMajor        Set to @c true to copy the array in row-major order, @n
 410          *                                                      else @c copy in column-major order
 411          * @exception   E_SUCCESS       The method is successful.
 412          * @exception   E_INVALID_ARG   The @c pArray is @c null.
 413          */
 414         result SetValue(const double* pArray, bool rowMajor = true);
 415
 416         /**
 417          * Sets the matrix members of current instance of %DoubleMatrix to zero.
 418          *
 419          * @since 2.0
 420          */
 421         void SetAsNull(void);
 422
 423         /**
 424          * Subtracts the value of the specified instance from the current instance of %DoubleMatrix.
 425          *
 426          * @since 2.0
 427          *
 428          * @return              An error code
 429          * @param[in]   matrix  An instance of %DoubleMatrix
 430          * @exception   E_SUCCESS       The method is successful.
 431          * @exception   E_INVALID_ARG   Either row or column count of the current instance is not same with that of the specified instance.
 432          */
 433         result Subtract(const DoubleMatrix& matrix);
 434
 435         /**
 436          * Subtracts the value from each matrix members of the current instance of %DoubleMatrix.
 437          *
 438          * @since 2.0
 439          *
 440          * @param[in]   value   A @c double value to subtract
 441          */
 442         void SubtractToEachElement(double value);
 443
 444 private:
 445         /*
 446          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 447          *
 448          * @since       2.0
 449          */
 450         DoubleMatrix(void);
 451
 452         bool AllocateCapacity(int rowCount, int columnCount);
 453         void GetMinor(double** pSrc, double** pDest, int rowIndex, int columnIndex, int order) const;
 454         double CalculateDeterminant(double** pMatrix, int order) const;
 455
 456         friend class _DoubleMatrixImpl;
 457         class _DoubleMatrixImpl* __pImpl;
 458
 459         double** __pMatrix;
 460         int __row;
 461         int __column;
 462
 463 }; // DoubleMatrix
 464
 465 }} // Tizen::Base
 466
 467 #endif //_FBASE_DOUBLE_MATRIX_H_