CLHEP/Evaluator/Evaluator.h

0001 // -*- C++ -*-
0002 // $Id: Evaluator.h,v 1.2 2010/07/20 17:00:49 garren Exp $
0003 // ---------------------------------------------------------------------------
0004
0005 #ifndef HEP_EVALUATOR_H
0006 #define HEP_EVALUATOR_H
0007
0008 #include <string>
0009
0010 namespace HepTool {
0011
0012 /**
0013  * Evaluator of arithmetic expressions with an extendable dictionary.
0014  * Example:
0015  * @code
0016  *   #include "CLHEP/Evaluator/Evaluator.h"
0017  *   HepTool::Evaluator eval;
0018  *   eval.setStdMath();
0019  *   double res = eval.evaluate("sin(30*degree)");
0020  *   if (eval.status() != HepTool::Evaluator::OK) eval.print_error();
0021  * @endcode
0022  *
0023  * @author Evgeni Chernyaev <Evgueni.Tcherniaev@cern.ch>
0024  * @ingroup evaluator
0025  */
0026 class Evaluator {
0027  public:
0028
0029   /**
0030    * List of possible statuses.
0031    * Status of the last operation can be obtained with status().
0032    * In case if status() is an ERROR the corresponding error message
0033    * can be printed with print_error().
0034    *
0035    * @see status
0036    * @see error_position
0037    * @see print_error
0038    */
0039   enum {
0040     OK,                         /**< Everything OK */
0041     WARNING_EXISTING_VARIABLE,  /**< Redefinition of existing variable */
0042     WARNING_EXISTING_FUNCTION,  /**< Redefinition of existing function */
0043     WARNING_BLANK_STRING,       /**< Empty input string */
0044     ERROR_NOT_A_NAME,           /**< Not allowed sysmbol in the name of variable or function */
0045     ERROR_SYNTAX_ERROR,         /**< Systax error */
0046     ERROR_UNPAIRED_PARENTHESIS, /**< Unpaired parenthesis */
0047     ERROR_UNEXPECTED_SYMBOL,    /**< Unexpected sysbol */
0048     ERROR_UNKNOWN_VARIABLE,     /**< Non-existing variable */
0049     ERROR_UNKNOWN_FUNCTION,     /**< Non-existing function */
0050     ERROR_EMPTY_PARAMETER,      /**< Function call has empty parameter */
0051     ERROR_CALCULATION_ERROR     /**< Error during calculation */
0052   };
0053
0054   /**
0055    * Constructor.
0056    */
0057   Evaluator();
0058
0059   /**
0060    * Destructor.
0061    */
0062   ~Evaluator();
0063
0064   /**
0065    * Evaluates the arithmetic expression given as character string.
0066    * The expression may consist of numbers, variables and functions
0067    * separated by arithmetic (+, - , /, *, ^, **) and logical
0068    * operators (==, !=, >, >=, <, <=, &&, ||).
0069    *
0070    * @param  expression input expression.
0071    * @return result of the evaluation.
0072    * @see status
0073    * @see error_position
0074    * @see print_error
0075    */
0076   double evaluate(const char * expression);
0077
0078   /**
0079    * Returns status of the last operation with the evaluator.
0080    */
0081   int status() const;
0082
0083   /**
0084    * Returns position in the input string where the problem occured.
0085    */
0086   int error_position() const;
0087
0088   /**
0089    * Prints error message if status() is an ERROR.
0090    */
0091   void print_error() const;
0092   /**
0093    * get a string defining the error name
0094    */
0095   std::string error_name() const;
0096
0097   /**
0098    * Adds to the dictionary a variable with given value.
0099    * If a variable with such a name already exist in the dictionary,
0100    * then status will be set to WARNING_EXISTING_VARIABLE.
0101    *
0102    * @param name name of the variable.
0103    * @param value value assigned to the variable.
0104    */
0105   void setVariable(const char * name, double value);
0106
0107   /**
0108    * Adds to the dictionary a variable with an arithmetic expression
0109    * assigned to it.
0110    * If a variable with such a name already exist in the dictionary,
0111    * then status will be set to WARNING_EXISTING_VARIABLE.
0112    *
0113    * @param name name of the variable.
0114    * @param expression arithmetic expression.
0115    */
0116   void setVariable(const char * name, const char * expression);
0117
0118   /**
0119    * Adds to the dictionary a function without parameters.
0120    * If such a function already exist in the dictionary,
0121    * then status will be set to WARNING_EXISTING_FUNCTION.
0122    *
0123    * @param name function name.
0124    * @param fun pointer to the real function in the user code.
0125    */
0126   void setFunction(const char * name, double (*fun)());
0127
0128   /**
0129    * Adds to the dictionary a function with one parameter.
0130    * If such a function already exist in the dictionary,
0131    * then status will be set to WARNING_EXISTING_FUNCTION.
0132    *
0133    * @param name function name.
0134    * @param fun pointer to the real function in the user code.
0135    */
0136   void setFunction(const char * name, double (*fun)(double));
0137
0138   /**
0139    * Adds to the dictionary a function with two parameters.
0140    * If such a function already exist in the dictionary,
0141    * then status will be set to WARNING_EXISTING_FUNCTION.
0142    *
0143    * @param name function name.
0144    * @param fun pointer to the real function in the user code.
0145    */
0146   void setFunction(const char * name, double (*fun)(double,double));
0147
0148   /**
0149    * Adds to the dictionary a function with three parameters.
0150    * If such a function already exist in the dictionary,
0151    * then status will be set to WARNING_EXISTING_FUNCTION.
0152    *
0153    * @param name function name.
0154    * @param fun pointer to the real function in the user code.
0155    */
0156   void setFunction(const char * name, double (*fun)(double,double,double));
0157
0158   /**
0159    * Adds to the dictionary a function with four parameters.
0160    * If such a function already exist in the dictionary,
0161    * then status will be set to WARNING_EXISTING_FUNCTION.
0162    *
0163    * @param name function name.
0164    * @param fun pointer to the real function in the user code.
0165    */
0166   void setFunction(const char * name,
0167            double (*fun)(double,double,double,double));
0168
0169   /**
0170    * Adds to the dictionary a function with five parameters.
0171    * If such a function already exist in the dictionary,
0172    * then status will be set to WARNING_EXISTING_FUNCTION.
0173    *
0174    * @param name function name.
0175    * @param fun pointer to the real function in the user code.
0176    */
0177   void setFunction(const char * name,
0178                    double (*fun)(double,double,double,double,double));
0179
0180   /**
0181    * Finds the variable in the dictionary.
0182    *
0183    * @param  name name of the variable.
0184    * @return true if such a variable exists, false otherwise.
0185    */
0186   bool findVariable(const char * name) const;
0187
0188   /**
0189    * Finds the function in the dictionary.
0190    *
0191    * @param  name name of the function to be unset.
0192    * @param  npar number of parameters of the function.
0193    * @return true if such a function exists, false otherwise.
0194    */
0195   bool findFunction(const char * name, int npar) const;
0196
0197   /**
0198    * Removes the variable from the dictionary.
0199    *
0200    * @param name name of the variable.
0201    */
0202   void removeVariable(const char * name);
0203
0204   /**
0205    * Removes the function from the dictionary.
0206    *
0207    * @param name name of the function to be unset.
0208    * @param npar number of parameters of the function.
0209    */
0210   void removeFunction(const char * name, int npar);
0211
0212   /**
0213    * Clear all settings.
0214    */
0215   void clear();
0216
0217   /**
0218    * Sets standard mathematical functions and constants.
0219    */
0220   void setStdMath();
0221
0222   /**
0223    * Sets system of units. Default is the SI system of units.
0224    * To set the CGS (Centimeter-Gram-Second) system of units
0225    * one should call:
0226    *   setSystemOfUnits(100., 1000., 1.0, 1.0, 1.0, 1.0, 1.0);
0227    *
0228    * To set system of units accepted in the GEANT4 simulation toolkit
0229    * one should call:
0230    * @code
0231    *   setSystemOfUnits(1.e+3, 1./1.60217733e-25, 1.e+9, 1./1.60217733e-10,
0232    *                    1.0, 1.0, 1.0);
0233    * @endcode
0234    *
0235    * The basic units in GEANT4 are:
0236    * @code
0237    *   millimeter              (millimeter = 1.)
0238    *   nanosecond              (nanosecond = 1.)
0239    *   Mega electron Volt      (MeV        = 1.)
0240    *   positron charge         (eplus      = 1.)
0241    *   degree Kelvin           (kelvin     = 1.)
0242    *   the amount of substance (mole       = 1.)
0243    *   luminous intensity      (candela    = 1.)
0244    *   radian                  (radian     = 1.)
0245    *   steradian               (steradian  = 1.)
0246    * @endcode
0247    */
0248   void setSystemOfUnits(double meter    = 1.0,
0249                         double kilogram = 1.0,
0250                         double second   = 1.0,
0251                         double ampere   = 1.0,
0252                         double kelvin   = 1.0,
0253                         double mole     = 1.0,
0254                         double candela  = 1.0);
0255
0256 private:
0257   void * p;                                 // private data
0258   Evaluator(const Evaluator &);             // copy constructor is not allowed
0259   Evaluator & operator=(const Evaluator &); // assignment is not allowed
0260 };
0261
0262 } // namespace HepTool
0263
0264 #endif /* HEP_EVALUATOR_H */