Logo Search packages:      
Sourcecode: libqalculate version File versions  Download package

ExpressionItem.h

Go to the documentation of this file.
/*
    Qalculate    

    Copyright (C) 2003-2006  Niklas Knutsson (nq@altern.org)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
*/

#ifndef EXPRESSIONITEM_H
#define EXPRESSIONITEM_H

#include <libqalculate/includes.h>

/** @file */

/// A name for an expression item (function, variable or unit)
/** An expression name has a text string representing a name and boolean values describing the names properties.
*/
00022 struct ExpressionName {
      
      /// If the name is an abbreviation.
00025       bool abbreviation;
      /// If the name has a suffix. If set to true, the part of the name after an underscore should be treated as a suffix.
00027       bool suffix;
      /// If the name contains unicode characters.
00029       bool unicode;
      /// If the name is in plural form.
00031       bool plural;
      /// If the name shall be used as a fixed reference. If this is set to true, the name will kept as it is in addition to translations of it.
00033       bool reference;
      /// If the name is unsuitable for user input.
00035       bool avoid_input;
      /// If the name is case sensitive. The default behavior is that abbreviations are case sensitive and other names are not.
00037       bool case_sensitive;
      /// The name.
00039       string name;
      
      /** Create an empty expression name. All properties are set to false.
      */
      ExpressionName();
      /** Create an expression name. All properties are set to false, unless the name only has one character in which case abbreviation and case_sesnsitive is set to true.
      *
      * @param sname The name.
      */
      ExpressionName(string sname);
      
      void operator = (const ExpressionName &ename);
      bool operator == (const ExpressionName &ename) const;
      bool operator != (const ExpressionName &ename) const;
      
};

/// 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.
*
*/
00080 class ExpressionItem {

  protected:

      string scat, stitle, sdescr;
      bool b_local, b_changed, b_builtin, b_approx, b_active, b_registered, b_hidden, b_destroyed;
      int i_ref, i_precision;
      vector<ExpressionItem*> v_refs;
      vector<ExpressionName> names;

  public:

      ExpressionItem(string cat_, string name_, string title_ = "", string descr_ = "", bool is_local = true, bool is_builtin = false, bool is_active = true);
      ExpressionItem();
      virtual ~ExpressionItem();
      
      virtual ExpressionItem *copy() const = 0;
      virtual void set(const ExpressionItem *item);
      
      virtual bool destroy();

      bool isRegistered() const;
      /// For internal use.
      void setRegistered(bool is_registered);

      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;

      /** Returns the name that best fulfils provided criterias. If two names are equally preferred, the one with lowest index is returned.
      *
      * @param abbreviation If an abbreviated name is preferred.
      * @param use_unicode If a name with unicode characters can be displayed/is preferred (prioritized if false).
      * @param plural If a name in plural form is preferred.
      * @param reference If a reference name is preferred (ignored if false).
      * @param 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.
      * @param can_display_unicode_string_arg Argument to pass to the above test function.
      * @returns The preferred name.
      */
      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;
      /** 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.
      *
      * @param abbreviation If an abbreviated name is preferred.
      * @param use_unicode If a name with unicode characters can be displayed/is preferred (prioritized if false).
      * @param plural If a name in plural form is preferred.
      * @param reference If a reference name is preferred (ignored if false).
      * @param 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.
      * @param can_display_unicode_string_arg Argument to pass to the above test function.
      * @returns The preferred name.
      */
      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;
      /** 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.
      *
      * @param abbreviation If an abbreviated name is preferred.
      * @param use_unicode If a name with unicode characters can be displayed/is preferred (prioritized if false).
      * @param plural If a name in plural form is preferred.
      * @param reference If a reference name is preferred (ignored if false).
      * @param 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.
      * @param can_display_unicode_string_arg Argument to pass to the above test function.
      * @returns The preferred name.
      */
      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;
      /** 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.
      *
      * @param index Index of name.
      * @returns Name for index or empty_expression_name if not found.
      */
      virtual const ExpressionName &getName(size_t index) const;
      /** Changes a name. If a name for the provided index is not present, it is added (equivalent to addName(ename, index, force)).
      *
      * @param ename The new name.
      * @param index Index of name to change.
      * @param force If true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.
      */
      virtual void setName(const ExpressionName &ename, size_t index = 1, bool force = true);
      /** 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)).
      *
      * @param sname The new name text string.
      * @param index Index of name to change.
      * @param force If true, expression items with conflicting names are replaced, otherwise . Only applies if the item is registered.
      */
      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;
      /** Removes all names. */
      virtual void clearNames();
      /** Removes all names that are not used for reference (ExpressionName.reference = true). */
      virtual void clearNonReferenceNames();
      virtual void removeName(size_t index);
      /** Checks if the expression item has a name with a specific text string.
      *
      * @param sname A text string to look for (not case sensitive)
      * @param 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 hasName(const string &sname, bool case_sensitive = true) const;
      /** Checks if the expression item has a name with a specific case sensitive text string.
      *
      * @param 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 size_t hasNameCaseSensitive(const string &sname) const;
      /** Searches for a name with specific properties.
      *
      * @param abbreviation If the name must be abbreviated. 1=true, 0=false, -1=ignore.
      * @param use_unicode If the name must have unicode characters. 1=true, 0=false, -1=ignore.
      * @param plural If the name must be in plural form. 1=true, 0=false, -1=ignore.
      * @param 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.
      * @param 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 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;

      /** Returns the title, descriptive name, of the item.
      *
      * @param 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)).
      * @param use_unicode If a name with unicode characters can be displayed/is preferred (passed to preferredName()).
      * @param 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()).
      * @param can_display_unicode_string_arg Argument to pass to the above test function (passed to preferredName()).
      * @returns Item title.
      */
      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;

      /** Sets the title, descriptive name, of the item. The title can not be used in expressions.
      *
      * @param title_ The new title.
      */
      virtual void setTitle(string title_);

      /** Returns the expression items description.
      *
      * @returns Description.
      */
      virtual const string &description() const;
      /** Sets the expression items description.
      *
      * @param descr_ Description.
      */
      virtual void setDescription(string descr_);

      /** Returns the category that the expression item belongs to. Subcategories are separated by '/'.
      *
      * @returns Category.
      */
      virtual const string &category() const;
      /** Sets which category the expression belongs to. Subcategories are separated by '/'.
      *
      * @param cat_ Category.
      */
      virtual void setCategory(string cat_);

      /** If the object has been changed since it was created/loaded. */
      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;

      /** 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 bool isApproximate() const;
      virtual void setApproximate(bool is_approx = true);

      /** 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 int precision() const;
      virtual void setPrecision(int prec);

      /** Returns if the expression item is active and can be used in expressions.
      *
      * @returns true if active.
      */
      virtual bool isActive() const;
      virtual void setActive(bool is_active);
      
      virtual bool isHidden() const;
      virtual void setHidden(bool is_hidden);

      /** 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 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);

      /** Returns the type of the expression item, corresponding to which subclass the object belongs to.
      *
      * @returns ::ExpressionItemType.
      */
      virtual int type() const = 0;
      /** Returns the subtype of the expression item, corresponding to which subsubclass the object belongs to.
      *
      * @returns Subtype/subsubclass.
      */
      virtual int subtype() const = 0;

};

#endif

Generated by  Doxygen 1.6.0   Back to index