gov.sns.tools.formula
Class FormulaInterpreter

java.lang.Object
  |
  +--gov.sns.tools.formula.FormulaInterpreter

public final class FormulaInterpreter

extends java.lang.Object

FormulaInterpreter is the public class used to evaluate a formula with a given set of variables provided by the user. You can create an instance of FormulaInterpreter, add functions to and supply variable values. You can evaluate a formula in terms of a text string and it will be evaluated in the context of the functions and variable values. You can add more functions and variable values as needed. Several math functions are already built in. Typically, you first compile a formula and then you evaluate the formula with the present variable values. You can change the variable values and simply call evaluate() to evaluate the formula with the new values. Compiling a formula generates an operator stack which is simply a list of operators which pops and pushes values to a value stack during formula evaluation. There are a variety of operators including arithmetic operators, function operators, logical operators and operators that simply push variable and constant values onto the value stack. This makes formula evaluation very efficient since all grammar parsing, operator ordering, variable lookup and function lookup was performed during formula compile time. An example formula might be: 5.4*exp(-x**2 - y**2) where you supply values for the variables x and y. The variable names are case sensitive and can be any series of alpha and numeric characters beginning with a single alpha character. The usual arithmetic-operator precedence rules apply.

See Also:

FunctionFactory

Field Summary

protected FormulaGrammar	grammar The grammar parses the formula text and generates the operator stack.
protected java.util.List	operatorStack Holds a list of operators in the order in which they should be evaluated.

Constructor Summary

FormulaInterpreter()
Creates a new instance of FormulaInterpreter

Method Summary

void	addFunction(Function function) Add a function to the available function list.
void	compile(java.lang.String formula) Calls the FormulaGrammar to compile the formula.
double	evaluate() Evaluate the compiled formula by looping through the ordered list of operators that was generated at formula compile time.
double	evaluate(java.lang.String formula) Convenience method that allows you to compile and evaluate the specified formula.
boolean	hasVariable(java.lang.String name) Determine if a variable of the specified name exists.
void	setVariable(java.lang.String name, double value) Set the named variable to the specified value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

operatorStack

protected java.util.List operatorStack

Holds a list of operators in the order in which they should be evaluated.

grammar

protected FormulaGrammar grammar

The grammar parses the formula text and generates the operator stack.

Constructor Detail

FormulaInterpreter

public FormulaInterpreter()

Creates a new instance of FormulaInterpreter

Method Detail

addFunction

public final void addFunction(Function function)

Add a function to the available function list.

Parameters:

function - the function to add to the interpreter lookup table

See Also:

Function, FunctionFactory

setVariable

public final void setVariable(java.lang.String name,
                              double value)

Set the named variable to the specified value. Overrides the previous value (if any) of the variable.

Parameters:

name - name of the variable

value - value assigned to the variable

hasVariable

public final boolean hasVariable(java.lang.String name)

Determine if a variable of the specified name exists. Note that if this method returns true it does not imply that the formula specifies the variable since one may set a variable in the interpreter even if it is not defined in the formula.

Parameters:

name - The name of the variable for which to check.

Returns:

true if the variable exists; false otherwise.

evaluate

public final double evaluate()

Evaluate the compiled formula by looping through the ordered list of operators that was generated at formula compile time.

Returns:

The result of evaluating the compiled formula with the present variable values.

See Also:

compile(java.lang.String)

evaluate

public final double evaluate(java.lang.String formula)
                      throws ParseException

Convenience method that allows you to compile and evaluate the specified formula.

Returns:

The result of evaluating the formula with the present variable values.

Throws:

ParseException - Thrown when the formula cannot be correctly parsed.

See Also:

compile(java.lang.String), evaluate()

compile

public final void compile(java.lang.String formula)
                   throws ParseException

Calls the FormulaGrammar to compile the formula.

Throws:

ParseException - Thrown when the formula cannot be correctly parsed.