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 #pragma once
  21
  22 /* Function descriptions for function wizard / autopilot */
  23
  24 #include "scfuncs.hxx"
  25
  26 #include <formula/IFunctionDescription.hxx>
  27 #include <sal/types.h>
  28 #include <rtl/ustring.hxx>
  29 #include <optional>
  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 final : 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 _rArguments
  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 OUString 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 maximum number of (variable) arguments
 124
 125       @return   maximum number of arguments, or 0 if there is no specific limit other than the general limit
 126     */
 127     virtual sal_uInt32 getVarArgsLimit() const override ;
 128
 129     /**
 130       Returns description of parameter at given position
 131
 132       @param _nPos
 133       Position of the parameter
 134
 135       @return   OUString description of the parameter
 136     */
 137     virtual OUString getParameterDescription(sal_uInt32 _nPos) const override ;
 138
 139     /**
 140       Returns name of parameter at given position
 141
 142       @param _nPos
 143       Position of the parameter
 144
 145       @return   OUString name of the parameter
 146     */
 147     virtual OUString getParameterName(sal_uInt32 _nPos) const override ;
 148
 149     /**
 150       Returns list of all parameter names
 151
 152       @return OUString containing separated list of all parameter names
 153     */
 154     OUString GetParamList() const;
 155
 156     /**
 157       Returns the full function signature
 158
 159       @return   OUString of the form "FUNCTIONNAME( parameter list )"
 160     */
 161     virtual OUString getSignature() const override ;
 162
 163     /**
 164       Returns the number of non-suppressed arguments
 165
 166       In case there are variable arguments the number of fixed non-suppressed
 167       arguments plus VAR_ARGS, same as for nArgCount (variable arguments can't
 168       be suppressed). The two functions are equal apart from return type and
 169       name.
 170
 171       @return    number of non-suppressed arguments
 172     */
 173     sal_uInt16  GetSuppressedArgCount() const;
 174     virtual sal_Int32 getSuppressedArgumentCount() const override ;
 175
 176     /**
 177       Requests function data from AddInCollection
 178
 179       Logs error message on failure for debugging purposes
 180     */
 181     virtual void initArgumentInfo()  const override;
 182
 183     /**
 184       Returns true if parameter at given position is optional
 185
 186       @param _nPos
 187       Position of the parameter
 188
 189       @return   true if optional, false if not optional
 190     */
 191     virtual bool isParameterOptional(sal_uInt32 _nPos) const override ;
 192
 193     /**
 194       Compares functions by name, respecting special characters
 195
 196       @param a
 197       pointer to first function descriptor
 198
 199       @param b
 200       pointer to second function descriptor
 201
 202       @return "(a < b)"
 203     */
 204     static bool compareByName(const ScFuncDesc* a, const ScFuncDesc* b);
 205
 206     /**
 207       Stores whether a parameter is optional or suppressed
 208     */
 209     struct ParameterFlags
 210     {
 211         bool    bOptional   :1;     /**< Parameter is optional */
 212
 213         ParameterFlags() : bOptional(false) {}
 214     };
 215
 216     std::optional<OUString> mxFuncName;         /**< Function name */
 217     std::optional<OUString> mxFuncDesc;         /**< Description of function */
 218     std::vector<OUString> maDefArgNames;          /**< Parameter name(s) */
 219     std::vector<OUString> maDefArgDescs;          /**< Description(s) of parameter(s) */
 220     ParameterFlags       *pDefArgFlags;           /**< Flags for each parameter */
 221     sal_uInt16            nFIndex;                /**< Unique function index */
 222     sal_uInt16            nCategory;              /**< Function category */
 223     sal_uInt16            nArgCount;              /**< All parameter count, suppressed and unsuppressed */
 224     sal_uInt16            nVarArgsStart;          /**< Start of variable arguments, for numbering */
 225     sal_uInt16            nVarArgsLimit;          /**< Limit maximum of (variable) arguments, for numbering */
 226     OUString              sHelpId;                /**< HelpId of function */
 227     bool                  bIncomplete         :1; /**< Incomplete argument info (set for add-in info from configuration) */
 228     bool                  mbHidden            :1; /**< Whether function is hidden */
 229 };
 230
 231 /**
 232   List of spreadsheet functions.
 233   Generated by retrieving functions from resources, AddIns and StarOne AddIns,
 234   and storing these in one linked list. Functions can be retrieved by index and
 235   by iterating through the list, starting at the First element, and retrieving
 236   the Next elements one by one.
 237
 238   The length of the longest function name can be retrieved for easier
 239   processing (i.e printing a function list).
 240 */
 241 class ScFunctionList
 242 {
 243 public:
 244     explicit ScFunctionList( bool bEnglishFunctionNames );
 245     ~ScFunctionList();
 246
 247     sal_uInt32 GetCount() const
 248                { return aFunctionList.size(); }
 249
 250     const ScFuncDesc* First();
 251
 252     const ScFuncDesc* Next();
 253
 254     const ScFuncDesc* GetFunction( sal_uInt32 nIndex ) const;
 255
 256     bool IsEnglishFunctionNames() const { return mbEnglishFunctionNames; }
 257
 258 private:
 259     ::std::vector<const ScFuncDesc*> aFunctionList; /**< List of functions */
 260     ::std::vector<const ScFuncDesc*>::iterator aFunctionListIter; /**< position in function list */
 261     bool mbEnglishFunctionNames;
 262 };
 263
 264 /**
 265   Category of spreadsheet functions.
 266
 267   Contains the name, index and function manager of a category,
 268   as well as a list of functions in the category
 269 */
 270 class ScFunctionCategory final : public formula::IFunctionCategory
 271 {
 272 public:
 273     ScFunctionCategory(const ::std::vector<const ScFuncDesc*>& _rCategory,sal_uInt32 _nCategory)
 274             : m_rCategory(_rCategory),m_nCategory(_nCategory){}
 275     virtual ~ScFunctionCategory(){}
 276
 277     /**
 278       @return count of functions in this category
 279     */
 280     virtual sal_uInt32 getCount() const override;
 281
 282     /**
 283       Gives the _nPos'th function in this category.
 284
 285       @param _nPos
 286       position of function in this category.
 287
 288       @return function at the _nPos position in this category, null if _nPos out of bounds.
 289     */
 290     virtual const formula::IFunctionDescription* getFunction(sal_uInt32 _nPos) const override;
 291
 292     /**
 293       @return index number of this category.
 294     */
 295     virtual sal_uInt32 getNumber() const override;
 296     virtual OUString getName() const override;
 297
 298 private:
 299     const ::std::vector<const ScFuncDesc*>& m_rCategory; /**< list of functions in this category */
 300     mutable OUString m_sName; /**< name of this category */
 301     sal_uInt32 m_nCategory; /**< index number of this category */
 302 };
 303
 304 #define SC_FUNCGROUP_COUNT  ID_FUNCTION_GRP_ADDINS
 305 /**
 306   Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
 307 */
 308 class ScFunctionMgr final : public formula::IFunctionManager
 309 {
 310 public:
 311     /**
 312       Retrieves all calc functions, generates cumulative ('All') category, and the categories.
 313
 314       The function lists of the categories are sorted by (case insensitive) function name
 315     */
 316             ScFunctionMgr();
 317     virtual ~ScFunctionMgr();
 318
 319     /**
 320       Returns name of category.
 321
 322       @param _nCategoryNumber
 323       index of category
 324
 325       @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
 326     */
 327     static OUString GetCategoryName(sal_uInt32 _nCategoryNumber );
 328
 329     /**
 330       Returns function by index.
 331
 332       Searches for a function with the function index nFIndex.
 333
 334       @param nFIndex
 335       index of the function
 336
 337       @return pointer to function with the index nFIndex, null if no such function was found.
 338     */
 339     const ScFuncDesc* Get( sal_uInt16 nFIndex ) const;
 340
 341     /**
 342       Returns the first function in category nCategory.
 343
 344       Selects nCategory as current category and returns first element of this.
 345
 346       @param nCategory
 347       index of requested category
 348
 349       @return pointer to first element in current category, null if nCategory out of bounds
 350     */
 351     const ScFuncDesc* First( sal_uInt16 nCategory = 0 ) const;
 352
 353     /**
 354       Returns the next function of the current category.
 355
 356       @return pointer to the next function in current category, null if current category not set.
 357     */
 358     const ScFuncDesc* Next() const;
 359
 360     /**
 361       @return number of categories, not counting the cumulative category ('All')
 362     */
 363     virtual sal_uInt32 getCount() const override;
 364
 365     /**
 366       Returns a category.
 367
 368       Returns an IFunctionCategory object for a category specified by nPos.
 369
 370       @param nPos
 371       the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
 372
 373       @return pointer to an IFunctionCategory object, null if nPos out of bounds.
 374     */
 375     virtual const formula::IFunctionCategory* getCategory(sal_uInt32 nPos) const override;
 376
 377     /**
 378       Appends the last recently used functions.
 379
 380       Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
 381
 382       @param _rLastRUFunctions
 383       a vector of pointer to IFunctionDescription, by reference.
 384     */
 385     virtual void fillLastRecentlyUsedFunctions(::std::vector< const formula::IFunctionDescription*>& _rLastRUFunctions) const override;
 386
 387     /**
 388       Maps Etoken to character
 389
 390       Used for retrieving characters for parentheses and separators.
 391
 392       @param _eToken
 393       token for which, the corresponding character is retrieved
 394
 395       @return character
 396     */
 397     virtual sal_Unicode getSingleToken(const formula::IFunctionManager::EToken _eToken) const override;
 398
 399 private:
 400     std::vector<const ScFuncDesc*> aCatLists[MAX_FUNCCAT]; /**< array of all categories, 0 is the cumulative ('All') category */
 401     mutable std::map< sal_uInt32, std::shared_ptr<ScFunctionCategory> > m_aCategories; /**< map of category pos to IFunctionCategory */
 402     mutable std::vector<const ScFuncDesc*>::const_iterator pCurCatListIter; /**< position in current category */
 403     mutable std::vector<const ScFuncDesc*>::const_iterator pCurCatListEnd; /**< end of current category */
 404 };
 405
 406 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */