sc/inc/funcdesc.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 #ifndef INCLUDED_SC_INC_FUNCDESC_HXX
  21 #define INCLUDED_SC_INC_FUNCDESC_HXX
  22
  23 /* Function descriptions for function wizard / autopilot */
  24
  25 #include "scfuncs.hxx"
  26
  27 #include <formula/IFunctionDescription.hxx>
  28 #include <sal/types.h>
  29 #include <rtl/ustring.hxx>
  30 #include <optional>
  31 #include <map>
  32 #include <memory>
  33
  34 #define MAX_FUNCCAT 12  /* maximum number of categories for functions */
  35 #define LRU_MAX 10 /* maximal number of last recently used functions */
  36
  37 /**
  38   Stores and generates human readable descriptions for spreadsheet-functions,
  39   e.g.\ functions used in formulas in calc
  40 */
  41 class ScFuncDesc final : public formula::IFunctionDescription
  42 {
  43 public:
  44     ScFuncDesc();
  45     virtual ~ScFuncDesc();
  46
  47     /**
  48       Clears the object
  49
  50       Deletes all objects referenced by the pointers in the class,
  51       sets pointers to NULL, and all numerical variables to 0
  52     */
  53     void Clear();
  54
  55     /**
  56       Fills a mapping with indexes for non-suppressed arguments
  57
  58       Fills mapping from visible arguments to real arguments, e.g. if of 4
  59       parameters the second one is suppressed {0,2,3}. For VAR_ARGS
  60       parameters only one element is added to the end of the sequence.
  61
  62       @param _rArguments
  63       Vector, which the indices are written to
  64     */
  65     virtual void fillVisibleArgumentMapping(::std::vector<sal_uInt16>& _rArguments) const override ;
  66
  67     /**
  68       Returns the category of the function
  69
  70       @return    the category of the function
  71     */
  72     virtual const formula::IFunctionCategory* getCategory() const override ;
  73
  74     /**
  75       Returns the description of the function
  76
  77       @return    the description of the function, or an empty OUString if there is no description
  78     */
  79     virtual OUString getDescription() const override ;
  80
  81     /**
  82       Returns the function signature with parameters from the passed string array.
  83
  84       @return    function signature with parameters
  85     */
  86     virtual OUString getFormula(const ::std::vector< OUString >& _aArguments) const override ;
  87
  88     /**
  89       Returns the name of the function
  90
  91       @return    the name of the function, or an empty OUString if there is no name
  92     */
  93     virtual OUString getFunctionName() const override ;
  94
  95     /**
  96       Returns the help id of the function
  97
  98       @return   help id of the function
  99     */
 100     virtual OString getHelpId() const override ;
 101
 102     /** Returns whether function is hidden and not offered in the Function
 103         Wizard unless used in an expression.
 104
 105         @return flag whether function is hidden
 106      */
 107     virtual bool isHidden() const override;
 108
 109     /**
 110       Returns number of arguments
 111
 112       @return   number of arguments
 113     */
 114     virtual sal_uInt32 getParameterCount() const override ;
 115
 116     /**
 117       Returns start of variable arguments
 118
 119       @return   start of variable arguments
 120     */
 121     virtual sal_uInt32 getVarArgsStart() const override ;
 122
 123     /**
 124       Returns maximum number of (variable) arguments
 125
 126       @return   maximum number of arguments, or 0 if there is no specific limit other than the general limit
 127     */
 128     virtual sal_uInt32 getVarArgsLimit() const override ;
 129
 130     /**
 131       Returns description of parameter at given position
 132
 133       @param _nPos
 134       Position of the parameter
 135
 136       @return   OUString description of the parameter
 137     */
 138     virtual OUString getParameterDescription(sal_uInt32 _nPos) const override ;
 139
 140     /**
 141       Returns name of parameter at given position
 142
 143       @param _nPos
 144       Position of the parameter
 145
 146       @return   OUString name of the parameter
 147     */
 148     virtual OUString getParameterName(sal_uInt32 _nPos) const override ;
 149
 150     /**
 151       Returns list of all parameter names
 152
 153       @return OUString containing separated list of all parameter names
 154     */
 155     OUString GetParamList() const;
 156
 157     /**
 158       Returns the full function signature
 159
 160       @return   OUString of the form "FUNCTIONNAME( parameter list )"
 161     */
 162     virtual OUString getSignature() const override ;
 163
 164     /**
 165       Returns the number of non-suppressed arguments
 166
 167       In case there are variable arguments the number of fixed non-suppressed
 168       arguments plus VAR_ARGS, same as for nArgCount (variable arguments can't
 169       be suppressed). The two functions are equal apart from return type and
 170       name.
 171
 172       @return    number of non-suppressed arguments
 173     */
 174     sal_uInt16  GetSuppressedArgCount() const;
 175     virtual sal_Int32 getSuppressedArgumentCount() const override ;
 176
 177     /**
 178       Requests function data from AddInCollection
 179
 180       Logs error message on failure for debugging purposes
 181     */
 182     virtual void initArgumentInfo()  const override;
 183
 184     /**
 185       Returns true if parameter at given position is optional
 186
 187       @param _nPos
 188       Position of the parameter
 189
 190       @return   true if optional, false if not optional
 191     */
 192     virtual bool isParameterOptional(sal_uInt32 _nPos) const override ;
 193
 194     /**
 195       Compares functions by name, respecting special characters
 196
 197       @param a
 198       pointer to first function descriptor
 199
 200       @param b
 201       pointer to second function descriptor
 202
 203       @return "(a < b)"
 204     */
 205     static bool compareByName(const ScFuncDesc* a, const ScFuncDesc* b);
 206
 207     /**
 208       Stores whether a parameter is optional or suppressed
 209     */
 210     struct ParameterFlags
 211     {
 212         bool    bOptional   :1;     /**< Parameter is optional */
 213
 214         ParameterFlags() : bOptional(false) {}
 215     };
 216
 217     std::optional<OUString> mxFuncName;         /**< Function name */
 218     std::optional<OUString> mxFuncDesc;         /**< Description of function */
 219     std::vector<OUString> maDefArgNames;          /**< Parameter name(s) */
 220     std::vector<OUString> maDefArgDescs;          /**< Description(s) of parameter(s) */
 221     ParameterFlags       *pDefArgFlags;           /**< Flags for each parameter */
 222     sal_uInt16            nFIndex;                /**< Unique function index */
 223     sal_uInt16            nCategory;              /**< Function category */
 224     sal_uInt16            nArgCount;              /**< All parameter count, suppressed and unsuppressed */
 225     sal_uInt16            nVarArgsStart;          /**< Start of variable arguments, for numbering */
 226     sal_uInt16            nVarArgsLimit;          /**< Limit maximum of (variable) arguments, for numbering */
 227     OString               sHelpId;                /**< HelpId of function */
 228     bool                  bIncomplete         :1; /**< Incomplete argument info (set for add-in info from configuration) */
 229     bool                  mbHidden            :1; /**< Whether function is hidden */
 230 };
 231
 232 /**
 233   List of spreadsheet functions.
 234   Generated by retrieving functions from resources, AddIns and StarOne AddIns,
 235   and storing these in one linked list. Functions can be retrieved by index and
 236   by iterating through the list, starting at the First element, and retrieving
 237   the Next elements one by one.
 238
 239   The length of the longest function name can be retrieved for easier
 240   processing (i.e printing a function list).
 241 */
 242 class ScFunctionList
 243 {
 244 public:
 245     ScFunctionList();
 246     ~ScFunctionList();
 247
 248     sal_uInt32 GetCount() const
 249                { return aFunctionList.size(); }
 250
 251     const ScFuncDesc* First();
 252
 253     const ScFuncDesc* Next();
 254
 255     const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
 256
 257 private:
 258     ::std::vector<const ScFuncDesc*> aFunctionList; /**< List of functions */
 259     ::std::vector<const ScFuncDesc*>::iterator aFunctionListIter; /**< position in function list */
 260 };
 261
 262 /**
 263   Category of spreadsheet functions.
 264
 265   Contains the name, index and function manager of a category,
 266   as well as a list of functions in the category
 267 */
 268 class ScFunctionCategory final : public formula::IFunctionCategory
 269 {
 270 public:
 271     ScFunctionCategory(::std::vector<const ScFuncDesc*>* _pCategory,sal_uInt32 _nCategory)
 272             : m_pCategory(_pCategory),m_nCategory(_nCategory){}
 273     virtual ~ScFunctionCategory(){}
 274
 275     /**
 276       @return count of functions in this category
 277     */
 278     virtual sal_uInt32 getCount() const override;
 279
 280     /**
 281       Gives the _nPos'th function in this category.
 282
 283       @param _nPos
 284       position of function in this category.
 285
 286       @return function at the _nPos position in this category, null if _nPos out of bounds.
 287     */
 288     virtual const formula::IFunctionDescription* getFunction(sal_uInt32 _nPos) const override;
 289
 290     /**
 291       @return index number of this category.
 292     */
 293     virtual sal_uInt32 getNumber() const override;
 294     virtual OUString getName() const override;
 295
 296 private:
 297     ::std::vector<const ScFuncDesc*>* m_pCategory; /**< list of functions in this category */
 298     mutable OUString m_sName; /**< name of this category */
 299     sal_uInt32 m_nCategory; /**< index number of this category */
 300 };
 301
 302 #define SC_FUNCGROUP_COUNT  ID_FUNCTION_GRP_ADDINS
 303 /**
 304   Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
 305 */
 306 class ScFunctionMgr final : public formula::IFunctionManager
 307 {
 308 public:
 309     /**
 310       Retrieves all calc functions, generates cumulative ('All') category, and the categories.
 311
 312       The function lists of the categories are sorted by (case insensitive) function name
 313     */
 314             ScFunctionMgr();
 315     virtual ~ScFunctionMgr();
 316
 317     /**
 318       Returns name of category.
 319
 320       @param _nCategoryNumber
 321       index of category
 322
 323       @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
 324     */
 325     static OUString GetCategoryName(sal_uInt32 _nCategoryNumber );
 326
 327     /**
 328       Returns function by index.
 329
 330       Searches for a function with the function index nFIndex.
 331
 332       @param nFIndex
 333       index of the function
 334
 335       @return pointer to function with the index nFIndex, null if no such function was found.
 336     */
 337     const ScFuncDesc* Get( sal_uInt16 nFIndex ) const;
 338
 339     /**
 340       Returns the first function in category nCategory.
 341
 342       Selects nCategory as current category and returns first element of this.
 343
 344       @param nCategory
 345       index of requested category
 346
 347       @return pointer to first element in current category, null if nCategory out of bounds
 348     */
 349     const ScFuncDesc* First( sal_uInt16 nCategory = 0 ) const;
 350
 351     /**
 352       Returns the next function of the current category.
 353
 354       @return pointer to the next function in current category, null if current category not set.
 355     */
 356     const ScFuncDesc* Next() const;
 357
 358     /**
 359       @return number of categories, not counting the cumulative category ('All')
 360     */
 361     virtual sal_uInt32 getCount() const override;
 362
 363     /**
 364       Returns a category.
 365
 366       Returns an IFunctionCategory object for a category specified by nPos.
 367
 368       @param nPos
 369       the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
 370
 371       @return pointer to an IFunctionCategory object, null if nPos out of bounds.
 372     */
 373     virtual const formula::IFunctionCategory* getCategory(sal_uInt32 nPos) const override;
 374
 375     /**
 376       Appends the last recently used functions.
 377
 378       Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
 379
 380       @param _rLastRUFunctions
 381       a vector of pointer to IFunctionDescription, by reference.
 382     */
 383     virtual void fillLastRecentlyUsedFunctions(::std::vector< const formula::IFunctionDescription*>& _rLastRUFunctions) const override;
 384
 385     /**
 386       Maps Etoken to character
 387
 388       Used for retrieving characters for parentheses and separators.
 389
 390       @param _eToken
 391       token for which, the corresponding character is retrieved
 392
 393       @return character
 394     */
 395     virtual sal_Unicode getSingleToken(const formula::IFunctionManager::EToken _eToken) const override;
 396
 397 private:
 398     std::unique_ptr<std::vector<const ScFuncDesc*>> aCatLists[MAX_FUNCCAT]; /**< array of all categories, 0 is the cumulative ('All') category */
 399     mutable std::map< sal_uInt32, std::shared_ptr<ScFunctionCategory> > m_aCategories; /**< map of category pos to IFunctionCategory */
 400     mutable std::vector<const ScFuncDesc*>::iterator pCurCatListIter; /**< position in current category */
 401     mutable std::vector<const ScFuncDesc*>::iterator pCurCatListEnd; /**< end of current category */
 402 };
 403
 404 #endif // INCLUDED_SC_INC_FUNCDESC_HXX
 405
 406 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */