sc/inc/scmatrix.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #pragma once
  21
  22 #include "address.hxx"
  23 #include "matrixoperators.hxx"
  24 #include "types.hxx"
  25 #include <formula/errorcodes.hxx>
  26 #include "scdllapi.h"
  27 #include <svl/sharedstring.hxx>
  28 #include <svl/sharedstringpool.hxx>
  29
  30 #include <memory>
  31 #include <utility>
  32 #include <vector>
  33
  34 #define DEBUG_MATRIX 0
  35
  36 class ScInterpreter;
  37 class SvNumberFormatter;
  38 class ScMatrixImpl;
  39 enum class FormulaError : sal_uInt16;
  40
  41 namespace sc {
  42
  43 struct Compare;
  44 struct CompareOptions;
  45
  46 }
  47
  48 /**
  49  * Try NOT to use this struct.  This struct should go away in a hopefully
  50  * not so distant future.
  51  */
  52 struct ScMatrixValue
  53 {
  54     double fVal;
  55     svl::SharedString aStr;
  56     ScMatValType nType;
  57
  58     /// Only valid if ScMatrix methods indicate so!
  59     const svl::SharedString& GetString() const { return aStr; }
  60
  61     /// Only valid if ScMatrix methods indicate that this is no string!
  62     FormulaError GetError() const { return GetDoubleErrorValue(fVal); }
  63
  64     /// Only valid if ScMatrix methods indicate that this is a boolean
  65     bool GetBoolean() const         { return fVal != 0.0; }
  66
  67     ScMatrixValue() : fVal(0.0), nType(ScMatValType::Empty) {}
  68     ScMatrixValue(const ScMatrixValue& r) = default;
  69     ScMatrixValue& operator= (const ScMatrixValue& r) = default;
  70
  71     bool operator== (const ScMatrixValue& r) const
  72     {
  73         if (nType != r.nType)
  74             return false;
  75
  76         switch (nType)
  77         {
  78             case ScMatValType::Value:
  79             case ScMatValType::Boolean:
  80                 return fVal == r.fVal;
  81             break;
  82             default:
  83                 ;
  84         }
  85
  86         return aStr == r.aStr;
  87     }
  88
  89     bool operator!= (const ScMatrixValue& r) const
  90     {
  91         return !operator==(r);
  92     }
  93 };
  94
  95 /**
  96  * Matrix data type that can store values of mixed types.  Each element can
  97  * be one of the following types: numeric, string, boolean, empty, and empty
  98  * path.
  99  */
 100 class SC_DLLPUBLIC ScMatrix final
 101 {
 102     friend class ScMatrixImpl;
 103
 104     mutable size_t  nRefCnt;    // reference count
 105     mutable bool    mbCloneIfConst; // Whether the matrix is cloned with a CloneIfConst() call.
 106     std::unique_ptr<ScMatrixImpl> pImpl;
 107
 108     ScMatrix( const ScMatrix& ) = delete;
 109     ScMatrix& operator=( const ScMatrix&) = delete;
 110
 111 public:
 112     ScMatrix(SCSIZE nC, SCSIZE nR);
 113     ScMatrix(SCSIZE nC, SCSIZE nR, double fInitVal);
 114     ScMatrix( size_t nC, size_t nR, const std::vector<double>& rInitVals );
 115     ~ScMatrix();
 116
 117     typedef std::function<void(size_t, size_t, double)> DoubleOpFunction;
 118     typedef std::function<void(size_t, size_t, bool)> BoolOpFunction;
 119     typedef std::function<void(size_t, size_t, svl::SharedString)> StringOpFunction;
 120     typedef std::function<void(size_t, size_t)> EmptyOpFunction;
 121     typedef std::function<double(double, double)> CalculateOpFunction;
 122
 123     /**
 124      * When adding all numerical matrix elements for a scalar result such as
 125      * summation, the interpreter wants to separate the first non-zero value
 126      * with the rest of the summed values. This is necessary for better
 127      * numerical stability, unless we sort all by absolute values before
 128      * summing (not really an option) or use another algorithm, e.g. Kahan's
 129      * summation algorithm,
 130      * https://en.wikipedia.org/wiki/Kahan_summation_algorithm
 131      */
 132     template<typename tRes>
 133     struct IterateResultMultiple
 134     {
 135         std::vector<tRes> maAccumulator;
 136         size_t mnCount;
 137
 138         IterateResultMultiple(size_t nCount) :
 139             maAccumulator(0), mnCount(nCount) {}
 140     };
 141     typedef IterateResultMultiple<KahanSum> KahanIterateResultMultiple;
 142     typedef IterateResultMultiple<double> DoubleIterateResultMultiple;
 143
 144     /**
 145       * Iterator for executing one operation with the matrix data.
 146       */
 147     template<typename tRes>
 148     struct IterateResult
 149     {
 150         tRes maAccumulator;
 151         size_t mnCount;
 152
 153         IterateResult(tRes fAccumulator, size_t nCount)
 154             : maAccumulator(fAccumulator), mnCount(nCount) {}
 155     };
 156     typedef IterateResult<KahanSum> KahanIterateResult;
 157     typedef IterateResult<double> DoubleIterateResult;
 158
 159
 160     /** Checks nC or nR for zero and uses GetElementsMax() whether a matrix of
 161         the size of nC*nR could be allocated. A zero size (both nC and nR zero)
 162         matrix is allowed for later resize.
 163      */
 164     bool static IsSizeAllocatable( SCSIZE nC, SCSIZE nR );
 165
 166     /// Value or boolean.
 167     static bool IsValueType( ScMatValType nType )
 168     {
 169         return nType <= ScMatValType::Boolean;
 170     }
 171
 172     /// Boolean.
 173     static bool IsBooleanType( ScMatValType nType )
 174     {
 175         return nType == ScMatValType::Boolean;
 176     }
 177
 178     /// String, empty or empty path, but not value nor boolean.
 179     static bool IsNonValueType( ScMatValType nType )
 180     {
 181         return bool(nType & ScMatValType::NonvalueMask);
 182     }
 183
 184     /** String, but not empty or empty path or any other type.
 185         Not named IsStringType to prevent confusion because previously
 186         IsNonValueType was named IsStringType. */
 187     static bool IsRealStringType( ScMatValType nType )
 188     {
 189         return (nType & ScMatValType::NonvalueMask) == ScMatValType::String;
 190     }
 191
 192     /// Empty, but not empty path or any other type.
 193     static bool IsEmptyType( ScMatValType nType )
 194     {
 195         return (nType & ScMatValType::NonvalueMask) == ScMatValType::Empty;
 196     }
 197
 198     /// Empty path, but not empty or any other type.
 199     static bool IsEmptyPathType( ScMatValType nType )
 200     {
 201         return (nType & ScMatValType::NonvalueMask) == ScMatValType::EmptyPath;
 202     }
 203
 204     /** Clone the matrix. */
 205     ScMatrix* Clone() const;
 206
 207     /** Clone the matrix if mbCloneIfConst (immutable) is set, otherwise
 208         return _this_ matrix, to be assigned to a ScMatrixRef. */
 209     ScMatrix* CloneIfConst();
 210
 211     /** Set the matrix to mutable for CloneIfConst(), only the interpreter
 212         should do this and know the consequences. */
 213     void SetMutable();
 214
 215     /** Set the matrix to immutable for CloneIfConst(), only the interpreter
 216         should do this and know the consequences. */
 217     void SetImmutable() const;
 218
 219     /**
 220      * Resize the matrix to specified new dimension.
 221      */
 222     void Resize(SCSIZE nC, SCSIZE nR);
 223
 224     void Resize(SCSIZE nC, SCSIZE nR, double fVal);
 225
 226     /** Clone the matrix and extend it to the new size. nNewCols and nNewRows
 227         MUST be at least of the size of the original matrix. */
 228     ScMatrix* CloneAndExtend(SCSIZE nNewCols, SCSIZE nNewRows) const;
 229
 230     void IncRef() const;
 231     void DecRef() const;
 232
 233     void SetErrorInterpreter( ScInterpreter* p);
 234     void GetDimensions( SCSIZE& rC, SCSIZE& rR) const;
 235     SCSIZE GetElementCount() const;
 236     bool ValidColRow( SCSIZE nC, SCSIZE nR) const;
 237
 238     /** For a row vector or column vector, if the position does not point into
 239         the vector but is a valid column or row offset it is adapted such that
 240         it points to an element to be replicated, same column row 0 for a row
 241         vector, same row column 0 for a column vector. Else, for a 2D matrix,
 242         returns false.
 243      */
 244     bool ValidColRowReplicated( SCSIZE & rC, SCSIZE & rR ) const;
 245
 246     /** Checks if the matrix position is within the matrix. If it is not, for a
 247         row vector or column vector the position is adapted such that it points
 248         to an element to be replicated, same column row 0 for a row vector,
 249         same row column 0 for a column vector. Else, for a 2D matrix and
 250         position not within matrix, returns false.
 251      */
 252     bool ValidColRowOrReplicated( SCSIZE & rC, SCSIZE & rR ) const;
 253
 254     void PutDouble( double fVal, SCSIZE nC, SCSIZE nR);
 255     void PutDouble( double fVal, SCSIZE nIndex);
 256     void PutDouble(const double* pArray, size_t nLen, SCSIZE nC, SCSIZE nR);
 257
 258     void PutString( const svl::SharedString& rStr, SCSIZE nC, SCSIZE nR) ;
 259     void PutString( const svl::SharedString& rStr, SCSIZE nIndex) ;
 260     void PutString( const svl::SharedString* pArray, size_t nLen, SCSIZE nC, SCSIZE nR) ;
 261
 262     void PutEmpty( SCSIZE nC, SCSIZE nR);
 263
 264     /// Jump sal_False without path
 265     void PutEmptyPath( SCSIZE nC, SCSIZE nR) ;
 266     void PutError( FormulaError nErrorCode, SCSIZE nC, SCSIZE nR ) ;
 267     void PutBoolean( bool bVal, SCSIZE nC, SCSIZE nR) ;
 268
 269     void FillDouble( double fVal,
 270             SCSIZE nC1, SCSIZE nR1, SCSIZE nC2, SCSIZE nR2 ) ;
 271
 272     /** Put a column vector of doubles, starting at row nR, must fit into dimensions. */
 273     void PutDoubleVector( const ::std::vector< double > & rVec, SCSIZE nC, SCSIZE nR ) ;
 274
 275     /** Put a column vector of strings, starting at row nR, must fit into dimensions. */
 276     void PutStringVector( const ::std::vector< svl::SharedString > & rVec, SCSIZE nC, SCSIZE nR ) ;
 277
 278     /** Put a column vector of empties, starting at row nR, must fit into dimensions. */
 279     void PutEmptyVector( SCSIZE nCount, SCSIZE nC, SCSIZE nR ) ;
 280
 281     /** Put a column vector of empty results, starting at row nR, must fit into dimensions. */
 282     void PutEmptyResultVector( SCSIZE nCount, SCSIZE nC, SCSIZE nR ) ;
 283
 284     /** Put a column vector of empty paths, starting at row nR, must fit into dimensions. */
 285     void PutEmptyPathVector( SCSIZE nCount, SCSIZE nC, SCSIZE nR ) ;
 286
 287     /** May be used before obtaining the double value of an element to avoid
 288         passing its NAN around.
 289         @ATTENTION: MUST NOT be used if the element is a string!
 290                     Use GetErrorIfNotString() instead if not sure.
 291         @returns 0 if no error, else one of err... constants */
 292     FormulaError GetError( SCSIZE nC, SCSIZE nR) const ;
 293
 294     /** Use in ScInterpreter to obtain the error code, if any.
 295         @returns 0 if no error or string element, else one of err... constants */
 296     FormulaError GetErrorIfNotString( SCSIZE nC, SCSIZE nR) const
 297         { return IsValue( nC, nR) ? GetError( nC, nR) : FormulaError::NONE; }
 298
 299     /// @return 0.0 if empty or empty path, else value or DoubleError.
 300     double GetDouble( SCSIZE nC, SCSIZE nR) const ;
 301     /// @return 0.0 if empty or empty path, else value or DoubleError.
 302     double GetDouble( SCSIZE nIndex) const ;
 303     /// @return value or DoubleError or string converted to value.
 304     double GetDoubleWithStringConversion( SCSIZE nC, SCSIZE nR ) const ;
 305
 306     /// @return empty string if empty or empty path, else string content.
 307     svl::SharedString GetString( SCSIZE nC, SCSIZE nR) const ;
 308     /// @return empty string if empty or empty path, else string content.
 309     svl::SharedString GetString( SCSIZE nIndex) const ;
 310
 311     /** @returns the matrix element's string if one is present, otherwise the
 312         numerical value formatted as string, or in case of an error the error
 313         string is returned; an empty string for empty, a "FALSE" string for
 314         empty path. */
 315     svl::SharedString GetString( SvNumberFormatter& rFormatter, SCSIZE nC, SCSIZE nR) const ;
 316
 317     /// @ATTENTION: If bString the ScMatrixValue->pS may still be NULL to indicate
 318     /// an empty string!
 319     ScMatrixValue Get( SCSIZE nC, SCSIZE nR) const ;
 320
 321     /** @return <TRUE/> if string or any empty, empty cell, empty result, empty
 322         path, in fact non-value. */
 323     bool IsStringOrEmpty( SCSIZE nIndex ) const ;
 324
 325     /** @return <TRUE/> if string or any empty, empty cell, empty result, empty
 326         path, in fact non-value. */
 327     bool IsStringOrEmpty( SCSIZE nC, SCSIZE nR ) const ;
 328
 329     /// @return <TRUE/> if empty or empty cell or empty result, not empty path.
 330     bool IsEmpty( SCSIZE nC, SCSIZE nR ) const ;
 331
 332     /// @return <TRUE/> if empty cell, not empty or empty result or empty path.
 333     bool IsEmptyCell( SCSIZE nC, SCSIZE nR ) const ;
 334
 335     /// @return <TRUE/> if empty result, not empty or empty cell or empty path.
 336     bool IsEmptyResult( SCSIZE nC, SCSIZE nR ) const ;
 337
 338     /// @return <TRUE/> if empty path, not empty or empty cell or empty result.
 339     bool IsEmptyPath( SCSIZE nC, SCSIZE nR ) const ;
 340
 341     /// @return <TRUE/> if value or boolean.
 342     bool IsValue( SCSIZE nIndex ) const ;
 343
 344     /// @return <TRUE/> if value or boolean.
 345     bool IsValue( SCSIZE nC, SCSIZE nR ) const ;
 346
 347     /// @return <TRUE/> if value or boolean or empty or empty path.
 348     bool IsValueOrEmpty( SCSIZE nC, SCSIZE nR ) const ;
 349
 350     /// @return <TRUE/> if boolean.
 351     bool IsBoolean( SCSIZE nC, SCSIZE nR ) const ;
 352
 353     /// @return <TRUE/> if entire matrix is numeric, including booleans, with no strings or empties
 354     bool IsNumeric() const ;
 355
 356     void MatTrans( const ScMatrix& mRes) const ;
 357     void MatCopy ( const ScMatrix& mRes) const ;
 358
 359     // Convert ScInterpreter::CompareMat values (-1,0,1) to boolean values
 360     void CompareEqual() ;
 361     void CompareNotEqual() ;
 362     void CompareLess() ;
 363     void CompareGreater() ;
 364     void CompareLessEqual() ;
 365     void CompareGreaterEqual() ;
 366
 367     double And() const ;       // logical AND of all matrix values, or NAN
 368     double Or() const ;        // logical OR of all matrix values, or NAN
 369     double Xor() const ;       // logical XOR of all matrix values, or NAN
 370
 371     KahanIterateResult Sum( bool bTextAsZero, bool bIgnoreErrorValues = false ) const ;
 372     KahanIterateResult SumSquare( bool bTextAsZero, bool bIgnoreErrorValues = false ) const ;
 373     DoubleIterateResult Product( bool bTextAsZero, bool bIgnoreErrorValues = false ) const ;
 374     size_t Count(bool bCountStrings, bool bCountErrors, bool bIgnoreEmptyStrings = false) const ;
 375     size_t MatchDoubleInColumns(double fValue, size_t nCol1, size_t nCol2) const ;
 376     size_t MatchStringInColumns(const svl::SharedString& rStr, size_t nCol1, size_t nCol2) const ;
 377
 378     double GetMaxValue( bool bTextAsZero, bool bIgnoreErrorValues = false ) const ;
 379     double GetMinValue( bool bTextAsZero, bool bIgnoreErrorValues = false ) const ;
 380     double GetGcd() const ;
 381     double GetLcm() const ;
 382
 383     ScMatrixRef CompareMatrix(
 384         sc::Compare& rComp, size_t nMatPos, sc::CompareOptions* pOptions ) const ;
 385
 386     /**
 387      * Convert the content of matrix into a linear array of numeric values.
 388      * String elements are mapped to NaN's and empty elements are mapped to
 389      * either NaN or zero values.
 390      *
 391      * @param bEmptyAsZero if true empty elements are mapped to zero values,
 392      *                     otherwise they become NaN values.
 393      */
 394     void GetDoubleArray( std::vector<double>& rArray, bool bEmptyAsZero = true ) const ;
 395     void MergeDoubleArrayMultiply( std::vector<double>& rArray ) const ;
 396
 397     void NotOp(const ScMatrix& rMat) ;
 398     void NegOp(const ScMatrix& rMat) ;
 399     void AddOp(double fVal, const ScMatrix& rMat) ;
 400     void SubOp(bool bFlag, double fVal, const ScMatrix& rMat) ;
 401     void MulOp(double fVal, const ScMatrix& rMat) ;
 402     void DivOp(bool bFlag, double fVal, const ScMatrix& rMat) ;
 403     void PowOp(bool bFlag, double fVal, const ScMatrix& rMat) ;
 404
 405     KahanIterateResultMultiple CollectKahan(const std::vector<sc::op::kOp>& aOp) ;
 406
 407     void ExecuteOperation(const std::pair<size_t, size_t>& rStartPos, const std::pair<size_t, size_t>& rEndPos,
 408             DoubleOpFunction aDoubleFunc, BoolOpFunction aBoolFunc, StringOpFunction aStringFunc,
 409             EmptyOpFunction aEmptyFunc) const ;
 410
 411     void MatConcat(SCSIZE nMaxCol, SCSIZE nMaxRow, const ScMatrixRef& xMat1, const ScMatrixRef& xMat2,
 412             SvNumberFormatter& rFormatter, svl::SharedStringPool& rPool) ;
 413
 414     /** Apply binary operation to values from two input matrices, storing result into this matrix. */
 415     void ExecuteBinaryOp(SCSIZE nMaxCol, SCSIZE nMaxRow, const ScMatrix& rInputMat1, const ScMatrix& rInputMat2,
 416             ScInterpreter* pInterpreter, CalculateOpFunction op);
 417
 418 #if DEBUG_MATRIX
 419     void Dump() const;
 420 #endif
 421 };
 422
 423 inline void intrusive_ptr_add_ref(const ScMatrix* p)
 424 {
 425     p->IncRef();
 426 }
 427
 428 inline void intrusive_ptr_release(const ScMatrix* p)
 429 {
 430     p->DecRef();
 431 }
 432
 433 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */