UserFunction Class Reference

A user defined mathematical function. More...

`#include <Function.h>`

Inheritance diagram for UserFunction:

## Public Member Functions

| UserFunction (string cat_, string name_, string formula_, bool is_local=true, int argc_=-1, string title_="", string descr_="", int max_argc_=0, bool is_active=true)
| UserFunction (const UserFunction *function)
void | set (const ExpressionItem *item)
ExpressionItem * | copy () const
string | formula () const
string | internalFormula () const
int | calculate (MathStructure &mstruct, const MathStructure &vargs, const EvaluationOptions &eo)
void | setFormula (string new_formula, int argc_=-1, int max_argc_=0)
void | addSubfunction (string subfunction, bool precalculate=true)
void | setSubfunction (size_t index, string subfunction)
void | delSubfunction (size_t index)
void | clearSubfunctions ()
size_t | countSubfunctions () const
void | setSubfunctionPrecalculated (size_t index, bool precalculate)
const string & | getSubfunction (size_t index) const
bool | subfunctionPrecalculated (size_t index) const
int | subtype () const
Public Member Functions inherited from MathFunction
| MathFunction (string name_, int argc_, int max_argc_=0, string cat_="", string title_="", string descr_="", bool is_active=true)
| MathFunction (const MathFunction *function)
virtual int | type () const
string | example (bool raw_format=false, string name_string="") const
void | setExample (string new_example)
bool | testArgumentCount (int itmp)
virtual MathStructure | calculate (const string &eq, const EvaluationOptions &eo=default_evaluation_options)
virtual MathStructure | parse (const string &eq, const ParseOptions &po=default_parse_options)
virtual int | parse (MathStructure &mstruct, const string &eq, const ParseOptions &po=default_parse_options)
virtual MathStructure | calculate (MathStructure &vargs, const EvaluationOptions &eo=default_evaluation_options)
string | condition () const
string | printCondition ()
void | setCondition (string expression)
bool | testCondition (const MathStructure &vargs)
int | args () const
int | minargs () const
int | maxargs () const
int | args (const string &str, MathStructure &vargs, const ParseOptions &po=default_parse_options)
size_t | lastArgumentDefinitionIndex () const
Argument * | getArgumentDefinition (size_t index)
void | clearArgumentDefinitions ()
void | setArgumentDefinition (size_t index, Argument *argdef)
int | stringArgs (const string &str, vector< string > &svargs)
void | setDefaultValue (size_t arg_, string value_)
const string & | getDefaultValue (size_t arg_) const
void | appendDefaultValues (MathStructure &vargs)
MathStructure | produceVector (const MathStructure &vargs, int begin=-1, int end=-1)
MathStructure | produceArgumentsVector (const MathStructure &vargs, int begin=-1, int end=-1)
virtual bool | representsPositive (const MathStructure &, bool=false) const
virtual bool | representsNegative (const MathStructure &, bool=false) const
virtual bool | representsNonNegative (const MathStructure &, bool=false) const
virtual bool | representsNonPositive (const MathStructure &, bool=false) const
virtual bool | representsInteger (const MathStructure &, bool=false) const
virtual bool | representsNumber (const MathStructure &, bool=false) const
virtual bool | representsRational (const MathStructure &, bool=false) const
virtual bool | representsNonComplex (const MathStructure &, bool=false) const
virtual bool | representsReal (const MathStructure &, bool=false) const
virtual bool | representsComplex (const MathStructure &, bool=false) const
virtual bool | representsNonZero (const MathStructure &, bool=false) const
virtual bool | representsEven (const MathStructure &, bool=false) const
virtual bool | representsOdd (const MathStructure &, bool=false) const
virtual bool | representsUndefined (const MathStructure &) const
virtual bool | representsBoolean (const MathStructure &) const
virtual bool | representsNonMatrix (const MathStructure &) const
virtual bool | representsScalar (const MathStructure &) const
Public Member Functions inherited from ExpressionItem
| ExpressionItem (string cat_, string name_, string title_="", string descr_="", bool is_local=true, bool is_builtin=false, bool is_active=true)
virtual bool | destroy ()
bool | isRegistered () const
void | setRegistered (bool is_registered)
| For internal use.
virtual const string & | name (bool use_unicode=false, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual const string & | referenceName () const
virtual const ExpressionName & | preferredName (bool abbreviation=false, bool use_unicode=false, bool plural=false, bool reference=false, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual const ExpressionName & | preferredInputName (bool abbreviation=false, bool use_unicode=false, bool plural=false, bool reference=false, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual const ExpressionName & | preferredDisplayName (bool abbreviation=false, bool use_unicode=false, bool plural=false, bool reference=false, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual const ExpressionName & | getName (size_t index) const
virtual void | setName (const ExpressionName &ename, size_t index=1, bool force=true)
virtual void | setName (string sname, size_t index, bool force=true)
virtual void | addName (const ExpressionName &ename, size_t index=0, bool force=true)
virtual void | addName (string sname, size_t index=0, bool force=true)
virtual size_t | countNames () const
virtual void | clearNames ()
virtual void | clearNonReferenceNames ()
virtual void | removeName (size_t index)
virtual size_t | hasName (const string &sname, bool case_sensitive=true) const
virtual size_t | hasNameCaseSensitive (const string &sname) const
virtual const ExpressionName & | findName (int abbreviation=-1, int use_unicode=-1, int plural=-1, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual const string & | title (bool return_name_if_no_title=true, bool use_unicode=false, bool(*can_display_unicode_string_function)(const char *, void *)=NULL, void *can_display_unicode_string_arg=NULL) const
virtual void | setTitle (string title_)
virtual const string & | description () const
virtual void | setDescription (string descr_)
virtual const string & | category () const
virtual void | setCategory (string cat_)
virtual bool | hasChanged () const
virtual void | setChanged (bool has_changed)
virtual bool | isLocal () const
virtual bool | setLocal (bool is_local=true, int will_be_active=-1)
virtual bool | isBuiltin () const
virtual bool | isApproximate () const
virtual void | setApproximate (bool is_approx=true)
virtual int | precision () const
virtual void | setPrecision (int prec)
virtual bool | isActive () const
virtual void | setActive (bool is_active)
virtual bool | isHidden () const
virtual void | setHidden (bool is_hidden)
virtual int | refcount () const
virtual void | ref ()
virtual void | unref ()
virtual void | ref (ExpressionItem *o)
virtual void | unref (ExpressionItem *o)
virtual ExpressionItem * | getReferencer (size_t index=1) const
virtual bool | changeReference (ExpressionItem *o_from, ExpressionItem *o_to)

## Protected Attributes

string | sformula
string | sformula_calc
vector< string > | v_subs
vector< bool > | v_precalculate
Protected Attributes inherited from MathFunction
MathFunction_p * | priv
int | argc
int | max_argc
vector< string > | default_values
size_t | last_argdef_index
string | scondition
string | sexample
Protected Attributes inherited from ExpressionItem
string | scat
string | stitle
string | sdescr
bool | b_local
bool | b_changed
bool | b_builtin
bool | b_approx
bool | b_active
bool | b_registered
bool | b_hidden
bool | b_destroyed
int | i_ref
int | i_precision
vector< ExpressionItem * > | v_refs
vector< ExpressionName > | names

## Additional Inherited Members

Protected Member Functions inherited from MathFunction
bool | testArguments (MathStructure &vargs)
virtual MathStructure | createFunctionMathStructureFromVArgs (const MathStructure &vargs)
virtual MathStructure | createFunctionMathStructureFromSVArgs (vector< string > &svargs)

## Detailed Description

A user defined mathematical function.

User functions are functions defined using expression strings, representing mathematical formulas.

The expression/formula of a function is basically a normal expression with placeholders for arguments. These placeholders consists of a backslash and a letter — x, y, z for the 1st, 2nd and 3rd arguments and a to u for argument 4 to 24. They are replaced by entered arguments when a function is calculated. The placeholders naturally also decide the number of arguments that a function requires. For example the function for triangle area ("base * height / 2") has the name triangle and the formula "(\x*\y)/2", which gives that "triangle(2, 3)" equals "(2*3) / 2" and returns "3" as result. An argument can be used more than one time and all arguments must not necessarily be in order in the formula.

Additionally, optional arguments can be put in the formula with upper-case (X, Y, Z, ...) instead of lower-case letters (x, y, z, ...). The default value can be put in brackets after the letter (ex. "\X{2}"). The default value may be omitted and is then zero. All additional arguments after an optional argument must also be optional.

To simplify the formula and make it more efficient, subfunctions can be used. These works just like the main formula, using the arguments of it. Subfunctions are referenced in the formula using \index ('\2', '\2', '\3', ...). Even though it would be quite meaningless, the formula for triangle function could for example have a subfunction "\x*\y" and the formula "\1/2". Subfunctions must be added before the main formula is set.

## Member Function Documentation

## calculate()

int UserFunction::calculate | ( | MathStructure & | mstruct,
|  | const MathStructure & | vargs,
|  | const EvaluationOptions & | eo
| ) |  |

virtual

The main function for subclasses to reimplement. Calculates a value from arguments in vargs and puts it in mstruct.

This function expects the number of arguments to be equal to the maximum number of arguments, and checked by the argument definitions.

If the return value is negative, then argument -(return value) has been evaluated in mstruct. If -(return value) is greater than max arguments, then mstruct is a vector of evaluated argument values.

Parameters

  [out] | mstruct | Structure that is set with the result of the calculation.
  | vargs | Arguments passed to the mathematical function.
  | eo | Evaluation options.

Returns
  1 if the calculation was successful.

Reimplemented from MathFunction.

## formula()

string UserFunction::formula | ( |  | ) | const

Returns the external representation of the formula.

## internalFormula()

string UserFunction::internalFormula | ( |  | ) | const

Returns the internal representation of the formula.

## setFormula()

void UserFunction::setFormula | ( | string | new_formula,
|  | int | argc_ = `-1`,
|  | int | max_argc_ = `0`
| ) |  |

Sets the formula of the mathematical function.

Parameters

  new_formula | Formula/expression.
  arc_ | Minimum number of arguments or -1 to read from formula.
  max_argc_ | Maximum number of arguments (ignored if argc_ < 0)

## setSubfunction()

void UserFunction::setSubfunction | ( | size_t | index,
|  | string | subfunction
| ) |  |

Sets the formula for a subfunction.

Parameters

  index | Index (starting at 1).
  subfunction | Formula/expression.

## subtype()

int UserFunction::subtype | ( |  | ) | const

virtual

Returns the subtype of the mathematical function, corresponding to which subsubclass the object belongs to.

Returns
  FunctionSubtype.

Reimplemented from MathFunction.

The documentation for this class was generated from the following file:

- libqalculate/Function.h