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