com.japisoft.formula
Class Formula

java.lang.Object
  extended bycom.japisoft.formula.Formula

public class Formula
extends java.lang.Object

Resolver of Mathematical Expression.

Example of expression :( 1 / 2 ) * ( m * g ) ^2 + eval( m, g ) - m and g are symbols or variables - eval is a function with two parameters

JFormula supports simplest format expression like : 2x+3x^2...

Usage sample :

 Formula f = new Formula("2+cos(PI)");Variant res = f.evaluate();
  double r = res.getDoubleValue();
 

  Formula f = new Formula( "A=1\nB=A+1\nA+B" );
  Variant res = f.evaluate();
  double r = res.getDoubleValue(); // 3
  f.getValueForSymbol( "A" ).getDoubleValue() // 1
  f.getValueForSymbol( "B" ).getDoubleValue() // 2
 

  Formula f = new Formula( "A=2\nif ( A > 1 ) then true else false" );
  Variant res = f.evaluate();
  res.getBooleanValue() // true
 

a variable value is retrieved by a symbol table or by a SymbolResolver delegate. The symbol table is updated while evaluating (A=...) or by the user before evaluating calling setSymbolValue( "A", ... )

a function value is retrieved by the function library or by a function delegate FunctionResolver
For the previous cases, just call addSymbolResolver or/and addFunctionResolver with your delegate.

For overriding or create a new operator, call the getOperatorFactory. Note that each time you call the method setHighPrecisionMode the factory is updated and your last change can be lost.

More information at : http://www.japisoft.com

Version:
3.6
Author:
(c) 2002 - 2005 JAPISoft /

Field Summary
static int DEF_HP_SCALE
          This is the default scale for the high precision mode
static int DEF_ROUNDING_MODE
          Default rounding mode for high precision usage
static java.lang.String E_SYMBOL
          Name of the symbol for the Exponential value
static java.lang.String FALSE_SYMBOL
          Name of the symbol for the 'false' value
static java.lang.String PI_SYMBOL
          Name of the symbol for the PI value
static java.lang.String TRUE_SYMBOL
          Name of the symbol for the 'true' value
 
Constructor Summary
Formula()
          Default constructor
Formula(boolean highPrecisionMode)
          Update the inner formula evaluator for working with java.lang.BigDecimal rather than with double value.
Formula(Formula formulaContext)
          This is a way to share symbol values / resolvers between different various formula context
Formula(java.lang.String expression)
           
Formula(java.lang.String expression, boolean highPrevisionMode)
           
 
Method Summary
 void addFunctionResolver(FunctionResolver resolver)
          add a function resolver.
 void addSymbolResolver(SymbolResolver resolver)
          add a symbol resolver.
 Variant evaluate()
          This method will evaluate the current expression.
protected  FormulaContext getContext()
           
 java.lang.String getExpression()
           
 OperatorFactory getOperatorFactory()
           
 java.util.Enumeration getSymbolNames()
           
 java.util.Enumeration getSymbolsFromExpression()
           
 Variant getValueForFunction(java.lang.String functionName, ListOfArgument parameters)
           
 Variant getValueForSymbol(java.lang.String symbolName)
           
protected  void initDefaultSymbols()
          Insert the PI symbol and E the base of the natural logarithms.
 boolean isHighPrecisionMode()
           
 AbstractNode parse()
          Parse the expression and return a node for evaluation.
 void removeFunctionResolver(FunctionResolver resolver)
          Remove a known function resolver
 void removeSymbolResolver(SymbolResolver resolver)
          Remove a known symbol resolver
 void removeSymbolValue(java.lang.String symbol)
          Remove a symbol value
 void setExpression(java.io.InputStream reader)
          The stream is automatically closed
 void setExpression(java.io.Reader reader)
          The stream is automatically closed
 void setExpression(java.lang.String expression)
           
 void setFormulaTreeBuilder(FormulaTreeBuilder ftb)
          Update the builder from the parsing processing.
 void setHighPrecisionMode(boolean mode)
          Update the inner formula evaluator for working with java.lang.BigDecimal rather than with double value.
 void setOperatorFactory(OperatorFactory factory)
          Update the current operator factory
 void setParent(Formula parent)
          Deprecated. Call rather setShareFormulaContext
 void setShareFormulaContext(Formula context)
          This is a way to share symbol values / resolvers between different various formula context
 void setSymbolValue(java.lang.String symbol, java.math.BigDecimal value)
          Assign a BigDecimal value to a symbol.
 void setSymbolValue(java.lang.String symbol, boolean value)
          Assign a boolean value to a symbol.
 void setSymbolValue(java.lang.String symbol, double value)
          Assign a double value to a symbol.
 void setSymbolValue(java.lang.String symbol, java.lang.String value)
          Assign a string value to a symbol.
 void setSymbolValue(java.lang.String symbol, Variant value)
          Set a symbol value, this value will be used while resolving the formula expression.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PI_SYMBOL

public static java.lang.String PI_SYMBOL
Name of the symbol for the PI value


E_SYMBOL

public static java.lang.String E_SYMBOL
Name of the symbol for the Exponential value


TRUE_SYMBOL

public static java.lang.String TRUE_SYMBOL
Name of the symbol for the 'true' value


FALSE_SYMBOL

public static java.lang.String FALSE_SYMBOL
Name of the symbol for the 'false' value


DEF_ROUNDING_MODE

public static int DEF_ROUNDING_MODE
Default rounding mode for high precision usage


DEF_HP_SCALE

public static int DEF_HP_SCALE
This is the default scale for the high precision mode

Constructor Detail

Formula

public Formula(Formula formulaContext)
This is a way to share symbol values / resolvers between different various formula context


Formula

public Formula()
Default constructor


Formula

public Formula(boolean highPrecisionMode)
Update the inner formula evaluator for working with java.lang.BigDecimal rather than with double value.

Parameters:
highPrecisionMode - enable BigDecimal rather than double

Formula

public Formula(java.lang.String expression)
Parameters:
expression - Mathematical expression

Formula

public Formula(java.lang.String expression,
               boolean highPrevisionMode)
Parameters:
expression - Mathematical expression
Method Detail

initDefaultSymbols

protected void initDefaultSymbols()
Insert the PI symbol and E the base of the natural logarithms. You can remove both symbols by calling the removeSymbol method


setParent

public void setParent(Formula parent)
Deprecated. Call rather setShareFormulaContext

Parameters:
parent - a Formula parent using resolution information (resolvers, symbol table) if a variable or function is unknown for this formula. This is a way to share symbol values between different various formula context

setShareFormulaContext

public void setShareFormulaContext(Formula context)
This is a way to share symbol values / resolvers between different various formula context


setOperatorFactory

public void setOperatorFactory(OperatorFactory factory)
Update the current operator factory


getOperatorFactory

public OperatorFactory getOperatorFactory()
Returns:
the current operator factory

setSymbolValue

public void setSymbolValue(java.lang.String symbol,
                           Variant value)
Set a symbol value, this value will be used while resolving the formula expression. Note that the SymbolResolver delegate will not be invoked if a value exists for the symbol while resolving


setSymbolValue

public void setSymbolValue(java.lang.String symbol,
                           java.lang.String value)
Assign a string value to a symbol. It must be called before evaluating your expression


setSymbolValue

public void setSymbolValue(java.lang.String symbol,
                           boolean value)
Assign a boolean value to a symbol. It must be called before evaluating your expression


setSymbolValue

public void setSymbolValue(java.lang.String symbol,
                           double value)
Assign a double value to a symbol. It must be called before evaluating your expression


setSymbolValue

public void setSymbolValue(java.lang.String symbol,
                           java.math.BigDecimal value)
Assign a BigDecimal value to a symbol. It must be called before evaluating your expression


removeSymbolValue

public void removeSymbolValue(java.lang.String symbol)
Remove a symbol value


getSymbolNames

public java.util.Enumeration getSymbolNames()
Returns:
current known symbol names

addFunctionResolver

public void addFunctionResolver(FunctionResolver resolver)
add a function resolver. This is useful for resolving function while evaluating the current expression


removeFunctionResolver

public void removeFunctionResolver(FunctionResolver resolver)
Remove a known function resolver


addSymbolResolver

public void addSymbolResolver(SymbolResolver resolver)
add a symbol resolver. This is useful for resolving variable while evaluating the current expression


removeSymbolResolver

public void removeSymbolResolver(SymbolResolver resolver)
Remove a known symbol resolver


setExpression

public void setExpression(java.lang.String expression)
Parameters:
expression - Mathematical expression
Throws:
FormulaException - for null value

setExpression

public void setExpression(java.io.InputStream reader)
                   throws java.io.IOException
The stream is automatically closed

Parameters:
reader - An InputStream with a mathematical expression
Throws:
java.io.IOException

setExpression

public void setExpression(java.io.Reader reader)
                   throws java.io.IOException
The stream is automatically closed

Parameters:
reader - A Reader with a mathematical expression
Throws:
java.io.IOException

getExpression

public java.lang.String getExpression()
Returns:
the current expression

setFormulaTreeBuilder

public void setFormulaTreeBuilder(FormulaTreeBuilder ftb)
Update the builder from the parsing processing. This builder made a tree with node that can be evaluated. It is used when calling the parse method


getContext

protected FormulaContext getContext()
Returns:
the usage context for the formula class. This context to each node evaluation and to each operator inside the OperatorContext

parse

public AbstractNode parse()
                   throws EvaluateException
Parse the expression and return a node for evaluation. This operation shouldn't be recall for the same expression. Each time you want to evaluate a result you call the evaluate method

Throws:
EvaluateException

evaluate

public Variant evaluate()
                 throws EvaluateException
This method will evaluate the current expression. It will parse the expression the first one and evaluate only an the parsing tree result for each invokation until the expression will change

Throws:
EvaluateException

getValueForSymbol

public Variant getValueForSymbol(java.lang.String symbolName)
                          throws SymbolResolverException
Returns:
a symbol value using the symbol table and in a second time the SymbolResolver delegate. If no value is found in the current Formula, the function tries to find a value from a parent.
Throws:
SymbolResolverException - if it is unable to find a value or a valid symbol name

getSymbolsFromExpression

public java.util.Enumeration getSymbolsFromExpression()
                                               throws EvaluateException
Returns:
an Enumeration of the symbols of the current expression
Throws:
EvaluateException - for a wrong syntax expression

getValueForFunction

public Variant getValueForFunction(java.lang.String functionName,
                                   ListOfArgument parameters)
                            throws FunctionResolverException
Returns:
a function value using the FunctionResolver delegate. If no value is found in the current Formula, the function tries to find a value from a parent.
Throws:
FunctionResolverException - if it is unable to find a value or a valid function

setHighPrecisionMode

public void setHighPrecisionMode(boolean mode)
Update the inner formula evaluator for working with java.lang.BigDecimal rather than with double value. By default false. This method must be called before setting an expression.

Parameters:
mode - if true, it works in high precision

isHighPrecisionMode

public boolean isHighPrecisionMode()
Returns:
true if high precision evaluation