sc/inc/scmatrix.hxx

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