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