1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
20 #ifndef INCLUDED_SC_INC_FUNCDESC_HXX
21 #define INCLUDED_SC_INC_FUNCDESC_HXX
23 /* Function descriptions for function wizard / autopilot */
25 #include "scfuncs.hxx"
27 #include <formula/IFunctionDescription.hxx>
28 #include <sal/types.h>
29 #include <rtl/ustring.hxx>
33 #define MAX_FUNCCAT 12 /* maximum number of categories for functions */
34 #define LRU_MAX 10 /* maximal number of last recently used functions */
38 class ScFunctionCategory
;
42 Stores and generates human readable descriptions for spreadsheet-functions,
43 e.g.\ functions used in formulas in calc
45 class ScFuncDesc
: public formula::IFunctionDescription
49 virtual ~ScFuncDesc();
54 Deletes all objects referenced by the pointers in the class,
55 sets pointers to NULL, and all numerical variables to 0
60 Fills a mapping with indexes for non-suppressed arguments
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.
67 Vector, which the indices are written to
69 virtual void fillVisibleArgumentMapping(::std::vector
<sal_uInt16
>& _rArguments
) const override
;
72 Returns the category of the function
74 @return the category of the function
76 virtual const formula::IFunctionCategory
* getCategory() const override
;
79 Returns the description of the function
81 @return the description of the function, or an empty OUString if there is no description
83 virtual OUString
getDescription() const override
;
86 Returns the function signature with parameters from the passed string array.
88 @return function signature with parameters
90 virtual OUString
getFormula(const ::std::vector
< OUString
>& _aArguments
) const override
;
93 Returns the name of the function
95 @return the name of the function, or an empty OUString if there is no name
97 virtual OUString
getFunctionName() const override
;
100 Returns the help id of the function
102 @return help id of the function
104 virtual OString
getHelpId() const override
;
106 /** Returns whether function is hidden and not offered in the Function
107 Wizard unless used in an expression.
109 @return flag whether function is hidden
111 virtual bool isHidden() const override
;
114 Returns number of arguments
116 @return number of arguments
118 virtual sal_uInt32
getParameterCount() const override
;
121 Returns start of variable arguments
123 @return start of variable arguments
125 virtual sal_uInt32
getVarArgsStart() const override
;
128 Returns description of parameter at given position
131 Position of the parameter
133 @return OUString description of the parameter
135 virtual OUString
getParameterDescription(sal_uInt32 _nPos
) const override
;
138 Returns name of parameter at given position
141 Position of the parameter
143 @return OUString name of the parameter
145 virtual OUString
getParameterName(sal_uInt32 _nPos
) const override
;
148 Returns list of all parameter names
150 @return OUString containing separated list of all parameter names
152 OUString
GetParamList() const;
155 Returns the full function signature
157 @return OUString of the form "FUNCTIONNAME( parameter list )"
159 virtual OUString
getSignature() const override
;
162 Returns the number of non-suppressed arguments
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
169 @return number of non-suppressed arguments
171 sal_uInt16
GetSuppressedArgCount() const;
172 virtual sal_Int32
getSuppressedArgumentCount() const override
;
175 Requests function data from AddInCollection
177 Logs error message on failure for debugging purposes
179 virtual void initArgumentInfo() const override
;
182 Returns true if parameter at given position is optional
185 Position of the parameter
187 @return true if optional, false if not optional
189 virtual bool isParameterOptional(sal_uInt32 _nPos
) const override
;
192 Compares functions by name, respecting special characters
195 pointer to first function descriptor
198 pointer to second function descriptor
202 static bool compareByName(const ScFuncDesc
* a
, const ScFuncDesc
* b
);
205 Stores whether a parameter is optional or suppressed
207 struct ParameterFlags
209 bool bOptional
:1; /**< Parameter is optional */
211 ParameterFlags() : bOptional(false) {}
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 */
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.
236 The length of the longest function name can be retrieved for easier
237 processing (i.e printing a function list).
245 sal_uInt32
GetCount() const
246 { return aFunctionList
.size(); }
248 const ScFuncDesc
* First();
250 const ScFuncDesc
* Next();
252 const ScFuncDesc
* GetFunction( sal_uInt32 nIndex
) const;
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 */
261 Category of spreadsheet functions.
263 Contains the name, index and function manager of a category,
264 as well as a list of functions in the category
266 class ScFunctionCategory
: public formula::IFunctionCategory
269 ScFunctionCategory(::std::vector
<const ScFuncDesc
*>* _pCategory
,sal_uInt32 _nCategory
)
270 : m_pCategory(_pCategory
),m_nCategory(_nCategory
){}
271 virtual ~ScFunctionCategory(){}
274 @return count of functions in this category
276 virtual sal_uInt32
getCount() const override
;
279 Gives the _nPos'th function in this category.
282 position of function in this category.
284 @return function at the _nPos position in this category, null if _nPos out of bounds.
286 virtual const formula::IFunctionDescription
* getFunction(sal_uInt32 _nPos
) const override
;
289 @return index number of this category.
291 virtual sal_uInt32
getNumber() const override
;
292 virtual OUString
getName() const override
;
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 */
300 #define SC_FUNCGROUP_COUNT ID_FUNCTION_GRP_ADDINS
302 Stores spreadsheet functions in categories, including a cumulative ('All') category and makes them accessible.
304 class ScFunctionMgr
: public formula::IFunctionManager
308 Retrieves all calc functions, generates cumulative ('All') category, and the categories.
310 The function lists of the categories are sorted by (case insensitive) function name
313 virtual ~ScFunctionMgr();
316 Returns name of category.
318 @param _nCategoryNumber
321 @return name of the category specified by _nCategoryNumber, empty string if _nCategoryNumber out of bounds
323 static OUString
GetCategoryName(sal_uInt32 _nCategoryNumber
);
326 Returns function by index.
328 Searches for a function with the function index nFIndex.
331 index of the function
333 @return pointer to function with the index nFIndex, null if no such function was found.
335 const ScFuncDesc
* Get( sal_uInt16 nFIndex
) const;
338 Returns the first function in category nCategory.
340 Selects nCategory as current category and returns first element of this.
343 index of requested category
345 @return pointer to first element in current category, null if nCategory out of bounds
347 const ScFuncDesc
* First( sal_uInt16 nCategory
= 0 ) const;
350 Returns the next function of the current category.
352 @return pointer to the next function in current category, null if current category not set.
354 const ScFuncDesc
* Next() const;
357 @return number of categories, not counting the cumulative category ('All')
359 virtual sal_uInt32
getCount() const override
;
364 Returns an IFunctionCategory object for a category specified by nPos.
367 the index of the category, note that 0 maps to the first category not the cumulative ('All') category.
369 @return pointer to an IFunctionCategory object, null if nPos out of bounds.
371 virtual const formula::IFunctionCategory
* getCategory(sal_uInt32 nPos
) const override
;
374 Appends the last recently used functions.
376 Takes the last recently used functions, but maximal LRU_MAX, and appends them to the given vector _rLastRUFunctions.
378 @param _rLastRUFunctions
379 a vector of pointer to IFunctionDescription, by reference.
381 virtual void fillLastRecentlyUsedFunctions(::std::vector
< const formula::IFunctionDescription
*>& _rLastRUFunctions
) const override
;
384 Maps Etoken to character
386 Used for retrieving characters for parantheses and separators.
389 token for which, the corresponding character is retrieved
393 virtual sal_Unicode
getSingleToken(const formula::IFunctionManager::EToken _eToken
) const override
;
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 */
403 #endif // INCLUDED_SC_INC_FUNCDESC_HXX
405 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */