inc/FBaseFloatMatrix.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        FBaseFloatMatrix.h
  20  * @brief       This is the header file for the %FloatMatrix class.
  21  *
  22  * This header file contains the declarations of the %FloatMatrix class.
  23  *
  24  */
  25
  26 #ifndef _FBASE_FLOAT_MATRIX_H_
  27 #define _FBASE_FLOAT_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       FloatMatrix
  37  * @brief       This class encapsulates a two-dimensional matrix.
  38  *
  39  * @since 2.0
  40  *
  41  * The %FloatMatrix class provides a @c float precision, two-dimensional matrix class.
  42  *
  43  */
  44 class _OSP_EXPORT_ FloatMatrix
  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 %FloatMatrix
  54          */
  55         FloatMatrix(const FloatMatrix& 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         FloatMatrix(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         FloatMatrix(int rowCount, int columnCount, const float* 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         FloatMatrix(int rowCount, int columnCount, const float* pArray[]);
  90
  91         /**
  92          * This destructor overrides Tizen::Base::Object::~Object().
  93          *
  94          * @since 2.0
  95          */
  96         virtual ~FloatMatrix(void);
  97
  98         /**
  99          * Checks whether the current instance and the specified instance of %FloatMatrix 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 %FloatMatrix
 106          */
 107         bool operator ==(const FloatMatrix& rhs) const;
 108
 109         /**
 110          * Checks whether the current instance and the specified instance of %FloatMatrix 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 %FloatMatrix
 117          */
 118         bool operator !=(const FloatMatrix& 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 %FloatMatrix
 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         FloatMatrix& operator =(const FloatMatrix& rhs);
 133
 134         /**
 135          * Checks whether the current instance of %FloatMatrix equals the specified instance of %FloatMatrix.
 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 %FloatMatrix
 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 %FloatMatrix.
 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 %FloatMatrix.
 159          *
 160          * @since 2.0
 161          *
 162          * @return              An error code
 163          * @param[in]   matrix  An instance of %FloatMatrix
 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 FloatMatrix& matrix);
 168
 169         /**
 170          * Adds the value to each matrix members of current instance of %FloatMatrix.
 171          *
 172          * @since 2.0
 173          *
 174          * @param[in]   value   A @c float value to add
 175          */
 176         void AddToEachElement(float value);
 177
 178         /**
 179          * Gets the number of column in the current instance of %FloatMatrix.
 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 %FloatMatrix.
 189          *
 190          * @since 2.0
 191          *
 192          * @return      A pointer to float 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         float* GetColumnN(int columnIndex) const;
 198
 199         /**
 200          * Gets the determinant of the current instance of %FloatMatrix.
 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         float GetDeterminant(void) const;
 210
 211         /**
 212          * Gets the value at the specified row and column of the current instance of %FloatMatrix.
 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         float GetElement(int rowIndex, int columnIndex) const;
 223
 224         /**
 225          * Gets the inverse matrix of the current instance of %FloatMatrix.
 226          *
 227          * @since 2.0
 228          *
 229          * @return       A pointer to the instance of %FloatMatrix 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         FloatMatrix* GetInverseN(void) const;
 234
 235         /**
 236          * Gets the number of row in the current instance of %FloatMatrix.
 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 %FloatMatrix.
 246          *
 247          * @since 2.0
 248          *
 249          * @return      A pointer to @c float 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         float* GetRowN(int rowIndex) const;
 255
 256         /**
 257          * Gets the trace of the current instance of %FloatMatrix.
 258          *
 259          * @since 2.0
 260          *
 261          * @return              An error code
 262          * @param[out]  value   A @c float 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(float& value) const;
 267
 268         /**
 269          * Gets the transpose matrix of the current instance of %FloatMatrix.
 270          *
 271          * @since 2.0
 272          *
 273          * @return       A pointer to the instance of %FloatMatrix 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         FloatMatrix* 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 %FloatMatrix.
 301          *
 302          * @since 2.0
 303          *
 304          * @return              An error code
 305          * @param[in]   matrix  An instance of %FloatMatrix
 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 FloatMatrix& matrix);
 310
 311         /**
 312          * Multiplies the value to each matrix members of current instance of %FloatMatrix.
 313          *
 314          * @since 2.0
 315          *
 316          * @param[in]   value   A @c float value to multiply
 317          */
 318         void Multiply(float value);
 319
 320         /**
 321          * Negates the matrix members of current instance of %FloatMatrix.
 322          *
 323          * @since 2.0
 324          */
 325         void Negate(void);
 326
 327         /**
 328          * Sets the value of the current instance of %FloatMatrix 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 %FloatMatrix 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 %FloatMatrix 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 %FloatMatrix.
 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 float* pArray);
 372
 373         /**
 374          * Sets the values of the specified array to the specified row of the current instance of %FloatMatrix.
 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 float* pArray);
 385
 386         /**
 387          * Sets the value to the specified row and column of the current instance of %FloatMatrix.
 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 float 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, float value);
 400
 401         /**
 402          * Sets the values to the current instance of %FloatMatrix 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 false to copy in column-major order
 410          * @exception   E_SUCCESS       The method is successful.
 411          * @exception   E_INVALID_ARG   The pArray is @c null.
 412          */
 413         result SetValue(const float* pArray, bool rowMajor = true);
 414
 415         /**
 416          * Sets the matrix members of current instance of %FloatMatrix 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 %FloatMatrix.
 424          *
 425          * @since 2.0
 426          *
 427          * @return              An error code
 428          * @param[in]   matrix  An instance of %FloatMatrix
 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 FloatMatrix& matrix);
 433
 434         /**
 435          * Subtracts the value from each matrix members of current instance of %FloatMatrix.
 436          *
 437          * @since 2.0
 438          *
 439          * @param[in]   value   A @c float value to subtract
 440          */
 441         void SubtractToEachElement(float 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         FloatMatrix(void);
 450
 451         bool AllocateCapacity(int rowCount, int columnCount);
 452         void GetMinor(float** pSrc, float** pDest, int rowIndex, int columnIndex, int order) const;
 453         float CalculateDeterminant(float** pMatrix, int order) const;
 454
 455         friend class _FloatMatrixImpl;
 456         class _FloatMatrixImpl* __pImpl;
 457
 458         float** __pMatrix;
 459         int __row;
 460         int __column;
 461
 462 }; // FloatMatrix
 463
 464 }} // Tizen::Base
 465
 466 #endif //_FBASE_FLOAT_MATRIX_H_