libqalculate-3.20.0
Public Member Functions | Protected Attributes | List of all members
ExpressionItem Class Referenceabstract

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

#include <ExpressionItem.h>

Inheritance diagram for ExpressionItem:
MathFunction Unit Variable DataSet UserFunction AliasUnit CompositeUnit KnownVariable UnknownVariable AliasUnit_Composite DynamicVariable NowVariable PrecisionVariable TodayVariable TomorrowVariable UptimeVariable YesterdayVariable

Public Member Functions

 ExpressionItem (std::string cat_, std::string name_, std::string title_="", std::string descr_="", bool is_local=true, bool is_builtin=false, bool is_active=true)
 
virtual ExpressionItemcopy () const =0
 
virtual void set (const ExpressionItem *item)
 
virtual bool destroy ()
 
bool isRegistered () const
 
void setRegistered (bool is_registered)
 For internal use.
 
virtual const std::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 std::string & referenceName () const
 
virtual const ExpressionNamepreferredName (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 ExpressionNamepreferredInputName (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 ExpressionNamepreferredDisplayName (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 ExpressionNamegetName (size_t index) const
 
virtual void setName (const ExpressionName &ename, size_t index=1, bool force=true)
 
virtual void setName (std::string sname, size_t index, bool force=true)
 
virtual void addName (const ExpressionName &ename, size_t index=0, bool force=true)
 
virtual void addName (std::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 std::string &sname, bool case_sensitive=true) const
 
virtual size_t hasNameCaseSensitive (const std::string &sname) const
 
virtual const ExpressionNamefindName (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 std::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 (std::string title_)
 
virtual const std::string & description () const
 
virtual void setDescription (std::string descr_)
 
virtual const std::string & category () const
 
virtual void setCategory (std::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 ExpressionItemgetReferencer (size_t index=1) const
 
virtual bool changeReference (ExpressionItem *o_from, ExpressionItem *o_to)
 
virtual int type () const =0
 
virtual int subtype () const =0
 
virtual int id () const
 

Protected Attributes

std::string scat
 
std::string stitle
 
std::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
 
std::vector< ExpressionItem * > v_refs
 
std::vector< ExpressionNamenames
 

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

◆ category()

virtual const std::string& ExpressionItem::category ( ) const
virtual

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

Returns
Category.

◆ clearNames()

virtual void ExpressionItem::clearNames ( )
virtual

Removes all names.

◆ clearNonReferenceNames()

virtual void ExpressionItem::clearNonReferenceNames ( )
virtual

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

◆ description()

virtual const std::string& ExpressionItem::description ( ) const
virtual

Returns the expression items description.

Returns
Description.

◆ findName()

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
abbreviationIf the name must be abbreviated. 1=true, 0=false, -1=ignore.
use_unicodeIf the name must have unicode characters. 1=true, 0=false, -1=ignore.
pluralIf the name must be in plural form. 1=true, 0=false, -1=ignore.
can_display_unicode_string_functionFunction 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_argArgument to pass to the above test function.
Returns
The first found name with the specified properties or empty_expression_name if none found.

◆ getName()

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
indexIndex of name.
Returns
Name for index or empty_expression_name if not found.

◆ hasChanged()

virtual bool ExpressionItem::hasChanged ( ) const
virtual

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

◆ hasName()

virtual size_t ExpressionItem::hasName ( const std::string &  sname,
bool  case_sensitive = true 
) const
virtual

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

Parameters
snameA text string to look for (not case sensitive)
case_sensitiveIf the name is case sensitive.
Returns
Index of the name with the given text string or zero if such a name was not found.

◆ hasNameCaseSensitive()

virtual size_t ExpressionItem::hasNameCaseSensitive ( const std::string &  sname) const
virtual

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

Parameters
snameA 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.

◆ isActive()

virtual bool ExpressionItem::isActive ( ) const
virtual

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

Returns
true if active.

◆ isApproximate()

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

◆ precision()

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.

◆ preferredDisplayName()

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
abbreviationIf an abbreviated name is preferred.
use_unicodeIf a name with unicode characters can be displayed/is preferred (prioritized if false).
pluralIf a name in plural form is preferred.
referenceIf a reference name is preferred (ignored if false).
can_display_unicode_string_functionFunction 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_argArgument to pass to the above test function.
Returns
The preferred name.

◆ preferredInputName()

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
abbreviationIf an abbreviated name is preferred.
use_unicodeIf a name with unicode characters can be displayed/is preferred (prioritized if false).
pluralIf a name in plural form is preferred.
referenceIf a reference name is preferred (ignored if false).
can_display_unicode_string_functionFunction 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_argArgument to pass to the above test function.
Returns
The preferred name.

◆ preferredName()

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
abbreviationIf an abbreviated name is preferred.
use_unicodeIf a name with unicode characters can be displayed/is preferred (prioritized if false).
pluralIf a name in plural form is preferred.
referenceIf a reference name is preferred (ignored if false).
can_display_unicode_string_functionFunction 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_argArgument to pass to the above test function.
Returns
The preferred name.

◆ refcount()

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.

◆ setCategory()

virtual void ExpressionItem::setCategory ( std::string  cat_)
virtual

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

Parameters
cat_Category.

◆ setDescription()

virtual void ExpressionItem::setDescription ( std::string  descr_)
virtual

Sets the expression items description.

Parameters
descr_Description.

◆ setName() [1/2]

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
enameThe new name.
indexIndex of name to change.
forceIf true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.

◆ setName() [2/2]

virtual void ExpressionItem::setName ( std::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
snameThe new name text string.
indexIndex of name to change.
forceIf true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.

◆ setTitle()

virtual void ExpressionItem::setTitle ( std::string  title_)
virtual

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

Parameters
title_The new title.

◆ subtype()

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 KnownVariable, UnknownVariable, Variable, CompositeUnit, AliasUnit, Unit, UserFunction, MathFunction, and DataSet.

◆ title()

virtual const std::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_titleIf 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_unicodeIf a name with unicode characters can be displayed/is preferred (passed to preferredName()).
can_display_unicode_string_functionFunction 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_argArgument to pass to the above test function (passed to preferredName()).
Returns
Item title.

◆ type()

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 Variable, Unit, and MathFunction.


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