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 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 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     OString               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     ScFunctionList();
 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 private:
 257     ::std::vector<const ScFuncDesc*> aFunctionList; /**< List of functions */
 258     ::std::vector<const ScFuncDesc*>::iterator aFunctionListIter; /**< position in function list */
 259 };
 260
 261 /**
 262   Category of spreadsheet functions.
 263
 264   Contains the name, index and function manager of a category,
 265   as well as a list of functions in the category
 266 */
 267 class ScFunctionCategory final : public formula::IFunctionCategory
 268 {
 269 public:
 270     ScFunctionCategory(const ::std::vector<const ScFuncDesc*>& _rCategory,sal_uInt32 _nCategory)
 271             : m_rCategory(_rCategory),m_nCategory(_nCategory){}
 272     virtual ~ScFunctionCategory(){}
 273
 274     /**
 275       @return count of functions in this category
 276     */
 277     virtual sal_uInt32 getCount() const override;
 278
 279     /**
 280       Gives the _nPos'th function in this category.
 281
 282       @param _nPos
 283       position of function in this category.
 284
 285       @return function at the _nPos position in this category, null if _nPos out of bounds.
 286     */
 287     virtual const formula::IFunctionDescription* getFunction(sal_uInt32 _nPos) const override;
 288
 289     /**
 290       @return index number of this category.
 291     */
 292     virtual sal_uInt32 getNumber() const override;
 293     virtual OUString getName() const override;
 294
 295 private:
 296     const ::std::vector<const ScFuncDesc*>& m_rCategory; /**< list of functions in this category */
 297     mutable OUString m_sName; /**< name of this category */
 298     sal_uInt32 m_nCategory; /**< index number of this category */
 299 };
 300
 301 #define SC_FUNCGROUP_COUNT  ID_FUNCTION_GRP_ADDINS
 302 /**
 303   Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
 304 */
 305 class ScFunctionMgr final : public formula::IFunctionManager
 306 {
 307 public:
 308     /**
 309       Retrieves all calc functions, generates cumulative ('All') category, and the categories.
 310
 311       The function lists of the categories are sorted by (case insensitive) function name
 312     */
 313             ScFunctionMgr();
 314     virtual ~ScFunctionMgr();
 315
 316     /**
 317       Returns name of category.
 318
 319       @param _nCategoryNumber
 320       index of category
 321
 322       @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
 323     */
 324     static OUString GetCategoryName(sal_uInt32 _nCategoryNumber );
 325
 326     /**
 327       Returns function by index.
 328
 329       Searches for a function with the function index nFIndex.
 330
 331       @param nFIndex
 332       index of the function
 333
 334       @return pointer to function with the index nFIndex, null if no such function was found.
 335     */
 336     const ScFuncDesc* Get( sal_uInt16 nFIndex ) const;
 337
 338     /**
 339       Returns the first function in category nCategory.
 340
 341       Selects nCategory as current category and returns first element of this.
 342
 343       @param nCategory
 344       index of requested category
 345
 346       @return pointer to first element in current category, null if nCategory out of bounds
 347     */
 348     const ScFuncDesc* First( sal_uInt16 nCategory = 0 ) const;
 349
 350     /**
 351       Returns the next function of the current category.
 352
 353       @return pointer to the next function in current category, null if current category not set.
 354     */
 355     const ScFuncDesc* Next() const;
 356
 357     /**
 358       @return number of categories, not counting the cumulative category ('All')
 359     */
 360     virtual sal_uInt32 getCount() const override;
 361
 362     /**
 363       Returns a category.
 364
 365       Returns an IFunctionCategory object for a category specified by nPos.
 366
 367       @param nPos
 368       the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
 369
 370       @return pointer to an IFunctionCategory object, null if nPos out of bounds.
 371     */
 372     virtual const formula::IFunctionCategory* getCategory(sal_uInt32 nPos) const override;
 373
 374     /**
 375       Appends the last recently used functions.
 376
 377       Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
 378
 379       @param _rLastRUFunctions
 380       a vector of pointer to IFunctionDescription, by reference.
 381     */
 382     virtual void fillLastRecentlyUsedFunctions(::std::vector< const formula::IFunctionDescription*>& _rLastRUFunctions) const override;
 383
 384     /**
 385       Maps Etoken to character
 386
 387       Used for retrieving characters for parentheses and separators.
 388
 389       @param _eToken
 390       token for which, the corresponding character is retrieved
 391
 392       @return character
 393     */
 394     virtual sal_Unicode getSingleToken(const formula::IFunctionManager::EToken _eToken) const override;
 395
 396 private:
 397     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*>::const_iterator pCurCatListIter; /**< position in current category */
 400     mutable std::vector<const ScFuncDesc*>::const_iterator pCurCatListEnd; /**< end of current category */
 401 };
 402
 403 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */