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