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