# ExpressionItem Class Reference

Abstract base class for functions, variables and units. More...

`#include <ExpressionItem.h>`

Inheritance diagram for ExpressionItem:

List of all members.

## Public Member Functions

| ExpressionItem (string cat_, string name_, string title_="", string descr_="", bool is_local=true, bool is_builtin=false, bool is_active=true)
virtual ExpressionItem * | copy () const =0
virtual void | set (const ExpressionItem *item)
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)
virtual int | type () const =0
virtual int | subtype () const =0

## Protected Attributes

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

## Detailed Description

Abstract base class for functions, variables and units.

Expression items have one or more names used to reference it in mathematical expressions and display them in a result. Each name must be fully unique, with the exception that functions can have names used by other types of items (for example "min" is used as a name for the minute unit but also for a function returning smallest value in a vector).

Items have an optional title and description for information to the end user. The categoy property is used to organize items, so that the end user can easily find them. Subcategories are separated by a slash, '/' (ex. "Physical Constants/Electromagnetic Constants").

A local item is created/edited by the end user.

A builtin item has defining properties that can/should not be edited by the user and is usually an item not loaded from the definition files.

An inactive item can not be used in expressions and can share the name of an active item.

The hidden propery defines if the item should be hidden from the end user.

Before an item can be used in expressions, it must be added to the Calculator object using CALCULATOR->addExpressionItem(). It is then said to be registered.

To delete an ExpressionItem object you should use destroy() to make sure that the item is removed from the Calculator and does not have any referrer.

## Member Function Documentation

virtual const ExpressionName& ExpressionItem::preferredName | ( | bool | abbreviation = `false`,
|  | bool | use_unicode = `false`,
|  | bool | plural = `false`,
|  | bool | reference = `false`,
|  | bool(*)(const char *, void *) | can_display_unicode_string_function = `NULL`,
|  | void * | can_display_unicode_string_arg = `NULL` |
| ) |  |  | const`[virtual]`

Returns the name that best fulfils provided criterias. If two names are equally preferred, the one with lowest index is returned.

Parameters:

  | abbreviation | If an abbreviated name is preferred.
  | use_unicode | If a name with unicode characters can be displayed/is preferred (prioritized if false).
  | plural | If a name in plural form is preferred.
  | reference | If a reference name is preferred (ignored if false).
  | can_display_unicode_string_function | Function that tests if the unicode characters in a name can be displayed. If the function returns false, the name will be rejected.
  | can_display_unicode_string_arg | Argument to pass to the above test function.

Returns:
  The preferred name.

virtual const ExpressionName& ExpressionItem::preferredInputName | ( | bool | abbreviation = `false`,
|  | bool | use_unicode = `false`,
|  | bool | plural = `false`,
|  | bool | reference = `false`,
|  | bool(*)(const char *, void *) | can_display_unicode_string_function = `NULL`,
|  | void * | can_display_unicode_string_arg = `NULL` |
| ) |  |  | const`[virtual]`

Returns the name that best fulfils provided criterias and is suitable for user input. If two names are equally preferred, the one with lowest index is returned.

Parameters:

  | abbreviation | If an abbreviated name is preferred.
  | use_unicode | If a name with unicode characters can be displayed/is preferred (prioritized if false).
  | plural | If a name in plural form is preferred.
  | reference | If a reference name is preferred (ignored if false).
  | can_display_unicode_string_function | Function that tests if the unicode characters in a name can be displayed. If the function returns false, the name will be rejected.
  | can_display_unicode_string_arg | Argument to pass to the above test function.

Returns:
  The preferred name.

virtual const ExpressionName& ExpressionItem::preferredDisplayName | ( | bool | abbreviation = `false`,
|  | bool | use_unicode = `false`,
|  | bool | plural = `false`,
|  | bool | reference = `false`,
|  | bool(*)(const char *, void *) | can_display_unicode_string_function = `NULL`,
|  | void * | can_display_unicode_string_arg = `NULL` |
| ) |  |  | const`[virtual]`

Returns the name that best fulfils provided criterias and is suitable for display. If two names are equally preferred, the one with lowest index is returned.

Parameters:

  | abbreviation | If an abbreviated name is preferred.
  | use_unicode | If a name with unicode characters can be displayed/is preferred (prioritized if false).
  | plural | If a name in plural form is preferred.
  | reference | If a reference name is preferred (ignored if false).
  | can_display_unicode_string_function | Function that tests if the unicode characters in a name can be displayed. If the function returns false, the name will be rejected.
  | can_display_unicode_string_arg | Argument to pass to the above test function.

Returns:
  The preferred name.

virtual const ExpressionName& ExpressionItem::getName | ( | size_t | index | ) | const`[virtual]`

Returns name for an index (starting at one). All functions can be traversed by starting at index one and increasing the index until empty_expression_name is returned.

Parameters:

  | index | Index of name.

Returns:
  Name for index or empty_expression_name if not found.

virtual void ExpressionItem::setName | ( | const ExpressionName & | ename,
|  | size_t | index = `1`,
|  | bool | force = `true` |
| ) |  |  | `[virtual]`

Changes a name. If a name for the provided index is not present, it is added (equivalent to addName(ename, index, force)).

Parameters:

  | ename | The new name.
  | index | Index of name to change.
  | force | If true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.

virtual void ExpressionItem::setName | ( | string | sname,
|  | size_t | index,
|  | bool | force = `true` |
| ) |  |  | `[virtual]`

Changes the text string of a name. If a name for the provided index is not present, it is added (equivalent to addName(sname, index, force)).

Parameters:

  | sname | The new name text string.
  | index | Index of name to change.
  | force | If true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.

virtual void ExpressionItem::clearNames | ( |  | ) | `[virtual]`

Removes all names.

virtual void ExpressionItem::clearNonReferenceNames | ( |  | ) | `[virtual]`

Removes all names that are not used for reference (ExpressionName.reference = true).

virtual size_t ExpressionItem::hasName | ( | const string & | sname,
|  | bool | case_sensitive = `true` |
| ) |  |  | const`[virtual]`

Checks if the expression item has a name with a specific text string.

Parameters:

  | sname | A text string to look for (not case sensitive)
  | case_sensitive | If the name is case sensitive.

Returns:
  Index of the name with the given text string or zero if such a name was not found.

virtual size_t ExpressionItem::hasNameCaseSensitive | ( | const string & | sname | ) | const`[virtual]`

Checks if the expression item has a name with a specific case sensitive text string.

Parameters:

  | sname | A text string to look for (case sensitive)

Returns:
  Index of the name with the given text string or zero if such a name was not found.

virtual const ExpressionName& ExpressionItem::findName | ( | int | abbreviation = `-1`,
|  | int | use_unicode = `-1`,
|  | int | plural = `-1`,
|  | bool(*)(const char *, void *) | can_display_unicode_string_function = `NULL`,
|  | void * | can_display_unicode_string_arg = `NULL` |
| ) |  |  | const`[virtual]`

Searches for a name with specific properties.

Parameters:

  | abbreviation | If the name must be abbreviated. 1=true, 0=false, -1=ignore.
  | use_unicode | If the name must have unicode characters. 1=true, 0=false, -1=ignore.
  | plural | If the name must be in plural form. 1=true, 0=false, -1=ignore.
  | can_display_unicode_string_function | Function that tests if the unicode characters in a name can be displayed. If the function returns false, the name will be rejected.
  | can_display_unicode_string_arg | Argument to pass to the above test function.

Returns:
  The first found name with the specified properties or empty_expression_name if none found.

virtual const string& ExpressionItem::title | ( | bool | return_name_if_no_title = `true`,
|  | bool | use_unicode = `false`,
|  | bool(*)(const char *, void *) | can_display_unicode_string_function = `NULL`,
|  | void * | can_display_unicode_string_arg = `NULL` |
| ) |  |  | const`[virtual]`

Returns the title, descriptive name, of the item.

Parameters:

  | return_name_if_no_title | If true, a name is returned if the title string is empty (using preferredName(false, use_unicode, false, false, can_display_unicode_string_function, can_display_unicode_string_arg)).
  | use_unicode | If a name with unicode characters can be displayed/is preferred (passed to preferredName()).
  | can_display_unicode_string_function | Function that tests if the unicode characters in a name can be displayed. If the function returns false, the name will be rejected (passed to preferredName()).
  | can_display_unicode_string_arg | Argument to pass to the above test function (passed to preferredName()).

Returns:
  Item title.

virtual void ExpressionItem::setTitle | ( | string | title_ | ) | `[virtual]`

Sets the title, descriptive name, of the item. The title can not be used in expressions.

Parameters:

  | title_ | The new title.

virtual const string& ExpressionItem::description | ( |  | ) | const`[virtual]`

Returns the expression items description.

Returns:
  Description.

virtual void ExpressionItem::setDescription | ( | string | descr_ | ) | `[virtual]`

Sets the expression items description.

Parameters:

  | descr_ | Description.

virtual const string& ExpressionItem::category | ( |  | ) | const`[virtual]`

Returns the category that the expression item belongs to. Subcategories are separated by '/'.

Returns:
  Category.

virtual void ExpressionItem::setCategory | ( | string | cat_ | ) | `[virtual]`

Sets which category the expression belongs to. Subcategories are separated by '/'.

Parameters:

  | cat_ | Category.

virtual bool ExpressionItem::hasChanged | ( |  | ) | const`[virtual]`

If the object has been changed since it was created/loaded.

virtual bool ExpressionItem::isApproximate | ( |  | ) | const`[virtual]`

If the item is approximate or exact. Note that an actual value associated with the item might have a have a lower precision. For, for example, a mathematical function this defines the precision of the formula, not the result.

Returns:
  true if the item is approximate

virtual int ExpressionItem::precision | ( |  | ) | const`[virtual]`

Returns precision of the item, if it is approximate. Note that an actual value associated with the item might have a have a lower precision. For, for example, a mathematical function this defines the precision of the formula, not the result.

virtual bool ExpressionItem::isActive | ( |  | ) | const`[virtual]`

Returns if the expression item is active and can be used in expressions.

Returns:
  true if active.

virtual int ExpressionItem::refcount | ( |  | ) | const`[virtual]`

The reference count is not used to delete the expression item when it becomes zero, but to stop from being deleted while it is in use.

virtual int ExpressionItem::type | ( |  | ) | const`[pure virtual]`

Returns the type of the expression item, corresponding to which subclass the object belongs to.

Returns:
  ExpressionItemType.

Implemented in MathFunction, Unit, and Variable.

virtual int ExpressionItem::subtype | ( |  | ) | const`[pure virtual]`

Returns the subtype of the expression item, corresponding to which subsubclass the object belongs to.

Returns:
  Subtype/subsubclass.

Implemented in DataSet, MathFunction, UserFunction, Unit, AliasUnit, CompositeUnit, Variable, UnknownVariable, and KnownVariable.

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

- libqalculate/ExpressionItem.h