inc/FBaseDoubleMatrix.h

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