sc/inc/scmatrix.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef SC_MATRIX_HXX
  29 #define SC_MATRIX_HXX
  30
  31 #include "global.hxx"
  32 #include "formula/intruref.hxx"
  33 #include "formula/errorcodes.hxx"
  34 #include <tools/string.hxx>
  35 #include "scdllapi.h"
  36
  37 class SvStream;
  38 class ScInterpreter;
  39 class SvNumberFormatter;
  40
  41 typedef BYTE ScMatValType;
  42 const ScMatValType SC_MATVAL_VALUE     = 0x00;
  43 const ScMatValType SC_MATVAL_BOOLEAN   = 0x01;
  44 const ScMatValType SC_MATVAL_STRING    = 0x02;
  45 const ScMatValType SC_MATVAL_EMPTY     = SC_MATVAL_STRING | 0x04; // STRING plus flag
  46 const ScMatValType SC_MATVAL_EMPTYPATH = SC_MATVAL_EMPTY | 0x08;  // EMPTY plus flag
  47 const ScMatValType SC_MATVAL_NONVALUE  = SC_MATVAL_EMPTYPATH;     // mask of all non-value bits
  48
  49 union ScMatrixValue
  50 {
  51     double fVal;
  52     String* pS;
  53
  54     /// Only valid if ScMatrix methods indicate so!
  55     const String& GetString() const     { return pS ? *pS : EMPTY_STRING; }
  56
  57     /// Only valid if ScMatrix methods indicate that this is no string!
  58     USHORT GetError() const         { return GetDoubleErrorValue( fVal); }
  59
  60     /// Only valid if ScMatrix methods indicate that this is a boolean
  61     bool GetBoolean() const         { return fVal != 0.; }
  62 };
  63
  64 /** Matrix representation of double values and strings.
  65
  66     @ATTENTION: optimized for speed and double values.
  67
  68     <p> Matrix elements are NOT initialized after construction!
  69
  70     <p> All methods using an SCSIZE nIndex parameter and all Is...() methods do
  71     NOT check the range for validity! However, the Put...() and Get...()
  72     methods using nCol/nRow parameters do check the range.
  73
  74     <p> Methods using nCol/nRow parameters do replicate a single row vector if
  75     nRow &gt; 0 and nCol &lt; nColCount, respectively a column vector if nCol
  76     &gt; 0 and nRow &lt; nRowCount.
  77
  78     <p> GetString( SCSIZE nIndex ) does not check if there really is a string,
  79     do this with IsString() first. GetString( SCSIZE nC, SCSIZE nR ) does check
  80     it and returns and empty string if there is no string. Both GetDouble()
  81     methods don't check for a string, do this with IsNumeric() or IsString() or
  82     IsValue() first.
  83
  84     <p> The GetString( SvNumberFormatter&, ...) methods return the matrix
  85     element's string if one is present, otherwise the numerical value is
  86     formatted as a string, or in case of an error the error string is returned.
  87
  88     <p> PutDouble() does not reset an eventual string! Use
  89     PutDoubleAndResetString() if that is wanted. Also the FillDouble...()
  90     methods don't reset strings. As a consequence memory leaks may occur if
  91     used wrong.
  92  */
  93 class SC_DLLPUBLIC ScMatrix
  94 {
  95     ScMatrixValue*  pMat;
  96     ScMatValType*   mnValType;
  97     ULONG           mnNonValue; // how many strings and empties
  98     ScInterpreter*  pErrorInterpreter;
  99     mutable ULONG   nRefCnt;    // reference count
 100     SCSIZE          nColCount;
 101     SCSIZE          nRowCount;
 102     bool            mbCloneIfConst;     // Whether the matrix is cloned with a CloneIfConst() call.
 103
 104     void ResetIsString();
 105     void DeleteIsString();
 106     void CreateMatrix( SCSIZE nC, SCSIZE nR);
 107     void Clear();
 108
 109     // pStr may be NULL, bFlag MUST NOT be 0
 110     void PutStringEntry( const String* pStr, BYTE bFlag, SCSIZE nIndex );
 111
 112     // only delete via Delete()
 113     ~ScMatrix();
 114
 115     // not implemented, prevent usage
 116     ScMatrix( const ScMatrix& );
 117     ScMatrix& operator=( const ScMatrix&);
 118
 119     void SetErrorAtInterpreter( USHORT nError) const;
 120
 121 public:
 122
 123     /// The maximum number of elements a matrix may have at runtime.
 124     inline static size_t GetElementsMax()
 125     {
 126         // Roughly 125MB in total, divided by 8+1 per element => 14M elements.
 127         const size_t nMemMax = 0x08000000 / (sizeof(ScMatrixValue) + sizeof(ScMatValType));
 128         // With MAXROWCOUNT==65536 and 128 columns => 8M elements ~72MB.
 129         const size_t nArbitraryLimit = (size_t)MAXROWCOUNT * 128;
 130         // Stuffed with a million rows would limit this to 14 columns.
 131         return nMemMax < nArbitraryLimit ? nMemMax : nArbitraryLimit;
 132     }
 133
 134     /// Value or boolean.
 135     inline static bool IsValueType( ScMatValType nType )
 136     {
 137         return nType <= SC_MATVAL_BOOLEAN;
 138     }
 139
 140     /// Boolean.
 141     inline static bool IsBooleanType( ScMatValType nType )
 142     {
 143         return nType == SC_MATVAL_BOOLEAN;
 144     }
 145
 146     /// String, empty or empty path, but not value nor boolean.
 147     inline static bool IsNonValueType( ScMatValType nType )
 148     {
 149         return (nType & SC_MATVAL_NONVALUE) != 0;
 150     }
 151
 152     /** String, but not empty or empty path or any other type.
 153         Not named IsStringType to prevent confusion because previously
 154         IsNonValueType was named IsStringType. */
 155     inline static bool IsRealStringType( ScMatValType nType )
 156     {
 157         return (nType & SC_MATVAL_NONVALUE) == SC_MATVAL_STRING;
 158     }
 159
 160     /// Empty, but not empty path or any other type.
 161     inline static bool IsEmptyType( ScMatValType nType )
 162     {
 163         return (nType & SC_MATVAL_NONVALUE) == SC_MATVAL_EMPTY;
 164     }
 165
 166     /// Empty path, but not empty or any other type.
 167     inline static bool IsEmptyPathType( ScMatValType nType )
 168     {
 169         return (nType & SC_MATVAL_NONVALUE) == SC_MATVAL_EMPTYPATH;
 170     }
 171
 172     /** If nC*nR results in more than GetElementsMax() entries, a 1x1 matrix is
 173         created instead and a double error value (errStackOverflow) is set.
 174         Compare nC and nR with a GetDimensions() call to check. */
 175     ScMatrix( SCSIZE nC, SCSIZE nR) : nRefCnt(0), mbCloneIfConst(true) { CreateMatrix( nC, nR); }
 176
 177     /** Clone the matrix. */
 178     ScMatrix* Clone() const;
 179
 180     /** Clone the matrix if mbCloneIfConst (immutable) is set, otherwise
 181         return _this_ matrix, to be assigned to a ScMatrixRef. */
 182     ScMatrix* CloneIfConst();
 183
 184     /** Set the matrix to (im)mutable for CloneIfConst(), only the interpreter
 185         should do this and know the consequences. */
 186     inline void SetImmutable( bool bVal ) { mbCloneIfConst = bVal; }
 187
 188     /**
 189      * Resize the matrix to specified new dimension.  Note that this operation
 190      * clears all stored values.
 191      */
 192     void Resize( SCSIZE nC, SCSIZE nR);
 193
 194     /** Clone the matrix and extend it to the new size. nNewCols and nNewRows
 195         MUST be at least of the size of the original matrix. */
 196     ScMatrix* CloneAndExtend( SCSIZE nNewCols, SCSIZE nNewRows ) const;
 197
 198     /// Disable refcounting forever, may only be deleted via Delete() afterwards.
 199     inline  void    SetEternalRef()         { nRefCnt = ULONG_MAX; }
 200     inline  bool    IsEternalRef() const    { return nRefCnt == ULONG_MAX; }
 201     inline  void    IncRef() const
 202     {
 203         if ( !IsEternalRef() )
 204             ++nRefCnt;
 205     }
 206     inline  void    DecRef() const
 207     {
 208         if ( nRefCnt > 0 && !IsEternalRef() )
 209             if ( --nRefCnt == 0 )
 210                 delete this;
 211     }
 212     inline  void    Delete()
 213     {
 214         if ( nRefCnt == 0 || IsEternalRef() )
 215             delete this;
 216         else
 217             --nRefCnt;
 218     }
 219
 220     void SetErrorInterpreter( ScInterpreter* p)
 221         { pErrorInterpreter = p; }
 222
 223     ScMatrix( SvStream& rStream);
 224     void Store( SvStream& rStream) const;
 225
 226     void GetDimensions( SCSIZE& rC, SCSIZE& rR) const
 227         { rC = nColCount; rR = nRowCount; };
 228     SCSIZE GetElementCount() const
 229         { return nColCount * nRowCount; }
 230     inline bool ValidColRow( SCSIZE nC, SCSIZE nR) const
 231         { return nC < nColCount && nR < nRowCount; }
 232     inline SCSIZE CalcOffset( SCSIZE nC, SCSIZE nR) const
 233         { return nC * nRowCount + nR; }
 234
 235     /** For a row vector or column vector, if the position does not point into
 236         the vector but is a valid column or row offset it is adapted such that
 237         it points to an element to be replicated, same column row 0 for a row
 238         vector, same row column 0 for a column vector. Else, for a 2D matrix,
 239         returns false.
 240      */
 241     inline bool ValidColRowReplicated( SCSIZE & rC, SCSIZE & rR ) const
 242     {
 243         if (nColCount == 1 && nRowCount == 1)
 244         {
 245             rC = 0;
 246             rR = 0;
 247             return true;
 248         }
 249         else if (nColCount == 1 && rR < nRowCount)
 250         {
 251             rC = 0;
 252             return true;
 253         }
 254         else if (nRowCount == 1 && rC < nColCount)
 255         {
 256             rR = 0;
 257             return true;
 258         }
 259         return false;
 260     }
 261
 262     /** Checks if the matrix position is within the matrix. If it is not, for a
 263         row vector or column vector the position is adapted such that it points
 264         to an element to be replicated, same column row 0 for a row vector,
 265         same row column 0 for a column vector. Else, for a 2D matrix and
 266         position not within matrix, returns false.
 267      */
 268     inline bool ValidColRowOrReplicated( SCSIZE & rC, SCSIZE & rR ) const
 269     {
 270         return ValidColRow( rC, rR) || ValidColRowReplicated( rC, rR);
 271     }
 272
 273
 274     void PutDouble( double fVal, SCSIZE nC, SCSIZE nR);
 275     void PutDouble( double fVal, SCSIZE nIndex)
 276         { pMat[nIndex].fVal = fVal; }
 277     void PutString( const String& rStr, SCSIZE nC, SCSIZE nR);
 278     void PutString( const String& rStr, SCSIZE nIndex);
 279     void PutEmpty( SCSIZE nC, SCSIZE nR);
 280     void PutEmpty( SCSIZE nIndex);
 281     /// Jump FALSE without path
 282     void PutEmptyPath( SCSIZE nC, SCSIZE nR);
 283     void PutEmptyPath( SCSIZE nIndex);
 284     void PutError( USHORT nErrorCode, SCSIZE nC, SCSIZE nR )
 285         { PutDouble( CreateDoubleError( nErrorCode ), nC, nR ); }
 286     void PutError( USHORT nErrorCode, SCSIZE nIndex )
 287         { PutDouble( CreateDoubleError( nErrorCode ), nIndex ); }
 288     void PutBoolean( bool bVal, SCSIZE nC, SCSIZE nR);
 289     void PutBoolean( bool bVal, SCSIZE nIndex);
 290
 291     void FillDouble( double fVal,
 292             SCSIZE nC1, SCSIZE nR1, SCSIZE nC2, SCSIZE nR2 );
 293
 294     /** May be used before obtaining the double value of an element to avoid
 295         passing its NAN around.
 296         @ATTENTION: MUST NOT be used if the element is a string!
 297                     Use GetErrorIfNotString() instead if not sure.
 298         @returns 0 if no error, else one of err... constants */
 299     USHORT GetError( SCSIZE nC, SCSIZE nR) const;
 300     USHORT GetError( SCSIZE nIndex) const
 301         { return pMat[nIndex].GetError(); }
 302
 303     /** Use in ScInterpreter to obtain the error code, if any.
 304         @returns 0 if no error or string element, else one of err... constants */
 305     USHORT GetErrorIfNotString( SCSIZE nC, SCSIZE nR) const
 306         { return IsValue( nC, nR) ? GetError( nC, nR) : 0; }
 307     USHORT GetErrorIfNotString( SCSIZE nIndex) const
 308         { return IsValue( nIndex) ? GetError( nIndex) : 0; }
 309
 310     /// @return 0.0 if empty or empty path, else value or DoubleError.
 311     double GetDouble( SCSIZE nC, SCSIZE nR) const;
 312     /// @return 0.0 if empty or empty path, else value or DoubleError.
 313     double GetDouble( SCSIZE nIndex) const
 314     {
 315         if ( pErrorInterpreter )
 316         {
 317             USHORT nError = GetDoubleErrorValue( pMat[nIndex].fVal);
 318             if ( nError )
 319                 SetErrorAtInterpreter( nError);
 320         }
 321         return pMat[nIndex].fVal;
 322     }
 323
 324     /// @return empty string if empty or empty path, else string content.
 325     const String& GetString( SCSIZE nC, SCSIZE nR) const;
 326     /// @return empty string if empty or empty path, else string content.
 327     const String& GetString( SCSIZE nIndex) const
 328         { return pMat[nIndex].GetString(); }
 329
 330     /** @returns the matrix element's string if one is present, otherwise the
 331         numerical value formatted as string, or in case of an error the error
 332         string is returned; an empty string for empty, a "FALSE" string for
 333         empty path. */
 334     String GetString( SvNumberFormatter& rFormatter, SCSIZE nC, SCSIZE nR) const;
 335     String GetString( SvNumberFormatter& rFormatter, SCSIZE nIndex) const;
 336
 337     /// @ATTENTION: If bString the ScMatrixValue->pS may still be NULL to indicate
 338     /// an empty string!
 339     const ScMatrixValue* Get( SCSIZE nC, SCSIZE nR, ScMatValType& nType) const;
 340
 341     /// @return <TRUE/> if string or empty or empty path, in fact non-value.
 342     BOOL IsString( SCSIZE nIndex ) const
 343         { return mnValType && IsNonValueType( mnValType[nIndex]); }
 344
 345     /// @return <TRUE/> if string or empty or empty path, in fact non-value.
 346     BOOL IsString( SCSIZE nC, SCSIZE nR ) const
 347     {
 348         ValidColRowReplicated( nC, nR );
 349         return mnValType && IsNonValueType( mnValType[ nC * nRowCount + nR ]);
 350     }
 351
 352     /// @return <TRUE/> if empty or empty path.
 353     BOOL IsEmpty( SCSIZE nIndex ) const
 354         { return mnValType && ((mnValType[nIndex] & SC_MATVAL_EMPTY) == SC_MATVAL_EMPTY); }
 355
 356     /// @return <TRUE/> if empty or empty path.
 357     BOOL IsEmpty( SCSIZE nC, SCSIZE nR ) const
 358     {
 359         ValidColRowReplicated( nC, nR );
 360         return mnValType && ((mnValType[ nC * nRowCount + nR ] & SC_MATVAL_EMPTY) == SC_MATVAL_EMPTY);
 361     }
 362
 363     /// @return <TRUE/> if empty path.
 364     BOOL IsEmptyPath( SCSIZE nC, SCSIZE nR ) const
 365     {
 366         ValidColRowReplicated( nC, nR );
 367         return mnValType && ((mnValType[ nC * nRowCount + nR ] & SC_MATVAL_EMPTYPATH) == SC_MATVAL_EMPTYPATH);
 368     }
 369
 370     /// @return <TRUE/> if empty path.
 371     BOOL IsEmptyPath( SCSIZE nIndex ) const
 372         { return mnValType && ((mnValType[nIndex] & SC_MATVAL_EMPTYPATH) == SC_MATVAL_EMPTYPATH); }
 373
 374     /// @return <TRUE/> if value or boolean.
 375     BOOL IsValue( SCSIZE nIndex ) const
 376         { return !mnValType || IsValueType( mnValType[nIndex]); }
 377
 378     /// @return <TRUE/> if value or boolean.
 379     BOOL IsValue( SCSIZE nC, SCSIZE nR ) const
 380     {
 381         ValidColRowReplicated( nC, nR );
 382         return !mnValType || IsValueType( mnValType[ nC * nRowCount + nR ]);
 383     }
 384
 385     /// @return <TRUE/> if value or boolean or empty or empty path.
 386     BOOL IsValueOrEmpty( SCSIZE nIndex ) const
 387         { return !mnValType || IsValueType( mnValType[nIndex] ) ||
 388             ((mnValType[nIndex] & SC_MATVAL_EMPTY) == SC_MATVAL_EMPTY); }
 389
 390     /// @return <TRUE/> if value or boolean or empty or empty path.
 391     BOOL IsValueOrEmpty( SCSIZE nC, SCSIZE nR ) const
 392     {
 393         ValidColRowReplicated( nC, nR );
 394         return !mnValType || IsValueType( mnValType[ nC * nRowCount + nR ]) ||
 395             ((mnValType[ nC * nRowCount + nR ] & SC_MATVAL_EMPTY) ==
 396              SC_MATVAL_EMPTY);
 397     }
 398
 399     /// @return <TRUE/> if boolean.
 400     BOOL IsBoolean( SCSIZE nIndex ) const
 401         { return mnValType && IsBooleanType( mnValType[nIndex]); }
 402
 403     /// @return <TRUE/> if boolean.
 404     BOOL IsBoolean( SCSIZE nC, SCSIZE nR ) const
 405     {
 406         ValidColRowReplicated( nC, nR );
 407         return mnValType && IsBooleanType( mnValType[ nC * nRowCount + nR ]);
 408     }
 409
 410     /// @return <TRUE/> if entire matrix is numeric, including booleans, with no strings or empties
 411     BOOL IsNumeric() const
 412         { return 0 == mnNonValue; }
 413
 414     void MatTrans( ScMatrix& mRes) const;
 415     void MatCopy ( ScMatrix& mRes) const;
 416
 417 //UNUSED2009-05 /** Copy upper left of this matrix to mRes matrix.
 418 //UNUSED2009-05     This matrix's dimensions must be greater or equal to the mRes matrix
 419 //UNUSED2009-05     dimensions.
 420 //UNUSED2009-05  */
 421 //UNUSED2009-05 void MatCopyUpperLeft( ScMatrix& mRes) const;
 422
 423     // Convert ScInterpreter::CompareMat values (-1,0,1) to boolean values
 424     void CompareEqual();
 425     void CompareNotEqual();
 426     void CompareLess();
 427     void CompareGreater();
 428     void CompareLessEqual();
 429     void CompareGreaterEqual();
 430
 431     double And();       // logical AND of all matrix values, or NAN
 432     double Or();        // logical OR of all matrix values, or NAN
 433
 434     // All other matrix functions  MatMult, MInv, ...  are in ScInterpreter
 435     // to be numerically safe.
 436 };
 437
 438
 439 typedef formula::SimpleIntrusiveReference< class ScMatrix > ScMatrixRef;
 440 typedef formula::SimpleIntrusiveReference< const class ScMatrix > ScConstMatrixRef;
 441
 442
 443 #endif  // SC_MATRIX_HXX