Class ExprEvaluator

java.lang.Object

ExprEvaluator

public class ExprEvaluator
extends java.lang.Object

Beta 6.0

The ExprEvaluator class is designed to be used in applications and applets when it is desired to allow the user to type in a mathematical expression and have the program calculate its values.

A two step process is used. Given a mathematical expression, a "build" method creates a binary expression tree representing the expression. It may be useful to think of the expression tree as the compiled version of the expression. Then an evaluate method is used to evaluate the binary expression tree. For example, the following code could be used in a simple situation to evaluate expression using the variables t, x, and y:
ExprEvaluator evaluator = new ExprEvaluator( );
double t = ...
double x = ...
double y = ...
String expression = ...
try {
evaluator.buildFromInfix(expression);
double value = evaluator.evaluate(t, x, y);
} catch (Exception e) {
...
}

All calculations are carried out with double precision real numbers.

If you are interested in handling multiple expressions, buildFromInfix returns the expression tree (the "compiled" version of the expression). This allows handling multiple expressions. See the "Evaluating multiple infix expressions" section below.

The class provides "build" methods that can handle prefix, infix and postfix expressions. Those expressions may contain the following:

• Nonnegative double precision numbers. The can be written as integers (25), decimals (2.235) or reals with exponents 1.2E3 (1200).
• Operators +, -, *, -, ^ (exponent), = (assignment to a variable). Parenthesis can be used in infix expressions.
• Variables a, b, c, ..., z.
• Functions such as abs, sin, log, and atan. 33 different functions are recognized including a user defined function.
• Constants PI (3.14159...) and E (2.718...)

There are separate build methods for prefix, infix, and postfix expressions. (If you are not familiar with these terms, we normally write mathematical expressions in infix. Postfix is sometimes called reverse Polish notation and is used by HP calculators and is convenient for computer work. You don't need to know how to use prefix and postfix to use this class. You will probably only want to use infix.) The following table show the equivalent prefix, infix, and postfix for some expressions emphasizing notation for functions and "=" signs.

Prefix	Infix	PostFix
/ + x y - t 7	(x+y)/(t-7)	x y + t 7 - /
= x 4	x = 4	x 4 =
= a = b = c * x y	a = b = c = x * y	a b c x y * = = =
sin x	sin(x)	x sin
abs - x y	abs(x - y)	x y - abs
max x y	max(x, y)	x y max

The "=" operator is optional and can be used in multiple assignments. For example: Both x + y and z = x + y (or + x y and = z + x y in prefix and x y + and z x y + = in postfix) return the same value. They differ in second expression also sets the value of z. The expression a = b = c = 3*x (or = a = b = c * 3 x in prefix and a b c 3 x * = = = in postfix) sets the values of a, b and c in addition to returning the value of 3*x (* 3 x in prefix).

Order of evaluation for infix expressions (the same as standard algebra and Visual Basic)

( )	Parenthesized expressions (highest priority)
functions
^	exponentials (right associative: 2^3^4 = 2^(3^4) )
leading + -	(as in -5)
* /
binary + -	(as in 4 - 3)
=	assignment (right associative: value on right is assigned to variable on left)) (lowest priority)

Processing one expression at a time

To simplify using ExprEvaluator, it "remembers" the last expression tree created by a build method. That expression tree is the default for the evaluate methods. Depending on the variables used, there are three general ways of evaluating expressions after the tree is built:
Only the "common" variables t, x, and y are used:
Use double evaluate(double t, double x, double y).
Example: evaluator.evaluate(10, 20, 30);.
See the above coding example or TrivialExample.java.
Only a few variables are used but they include "uncommon" variables:
Use setValueOf(char var, double value) as needed to set values of variables and then use evaluate( ). For example, if the expression uses variables a and b:
evaluator.setValueOf('a', 10);
evaluator.setValueOf('b', 20);
try {
result = evaluator.evaluate( );
} catch (Expression e) {
...
}
See TrivialExample3.java.
Many variables with values stored in an array:
Use evaluate(double[] values).
Example:
double [] variables = new double[26];
...
result = root.evaluate(variables);
See TrivialExample2.java.

Notes:

These techniques are not mutually exclusive. Internally, the same array is used to store variable values and is independent of the evaluate method is used. For example: Consider the sequence
evaluator.evaluate(10, 20, 30);
evaluator.evaluate( );
The second evaluate would use the values of t, x, and y resulting from the first evaluation. Typically, they would be t = 10, x = 20, and y = 30 but it is possible that those values were changed during the course of the first call to evaluate.

As another example, suppose that the expression is function that must be evaluated for many (x, y) pairs but depends on "constants" a and b. We could proceed as follows:
evaluator.setValueOf('a', 20);
evaluator.setValueOf('b', 30);
... inside a loop ...
xval = ...;
yval = ...;
value = evaluator.evaluate(0, xVal, yVal); // t is not used

Evaluating multiple infix expressions

ExprEvaluator has special methods that are useful when processing multiple infix expressions.

Evaluating functions for 2-D graph or table typically has one of the following levels of difficulty:

Type of problem	Comment
Evaluate or plot f(x)	The buildFromInfix and zero parameter evaluate method are completely capable of handling this situation. See TableExample1.java Alternatively, one may choose to use the buildFromInfix and evaluate(ExprTree) methods as suggested in the next item.
Evaluate or plot multiple functions of x	Assuming exprStr is string with the expression and valX is a double, use ExprTree expr = buildFromInfix(exprStr); setX(valX); double val = evaluate(expr);. See TableExample2.java
Use parametric functions for x and y. (There may be multiple sets of expressions.)	Use the technique from the previous example except use the buildFromInfix to build a tree for each x and y expression, set the value of the parameter, and then use evaluate for each of the expression trees to get the x and y values. See TableExample3.java
Use polar coordinates. (There may be multiple sets of expressions.)	ExprEvaluator provides a special method, convertToRect(r, theta), to convert polar coordinates to rectangular coordinates that may be needed to graph polar functions. If there is only 1 expression to be evaluated, then the buildFromInfix, setValueOf, and the zero parameter evaluate methods along with the convertToRect method are completely capable of handling this situation. However, if there is more than one expression to be evaluated, you should use buildFromInfix for each expression, set the values of the parameter(s) and then use evaluate(ExprTree) methods for each expression being evaluated. See TableExample4.java

While these techniques are designed for producing 2-D graphs, they may also be useful in other situations where it is desired to evaluate multiple functions. In fact, all the above examples just produce tables that could be used for plotting but there could be other uses as well.

The general code format when using multiple infix functions:
ExprEvaluator evaluator = new ExprEvaluator();
double x;
double firstX = ...;
double lastX = ...;
double incX = ...;
double y1, y2;
ExprTree tree1, tree2;
String expr1 = ...;
String expr2 = ...;
try {
tree1 = evaluator.buildFromInfix(expr1);
tree2 = evaluator.buildFromInfix(expr2);
for (x = firstX; x < lastX; x += incX) {
evaluator.setX(x);
y1 = evaluator.evaluate(tree1);
y2 = evaluator.evaluate(tree2);
...
}
} catch (Exception e) {
...
}

Functions

The ExprEvaluator can evaluate 34 functions, including 32 functions defined in Java's Math class, one unique function inspired by Excel (roundTo(val, num)) and a user defined function. You can search Java documentation for definitions of functions that you are unfamiliar with. The functions that can be used include the following:

• absolute value: abs(x).
• square root, cube root, and hypotenuse: sqrt(x), cbrt(x) and hypot(x, y).
• trig (using radians): sin(x), cos(x), tan(x), asin(x), acos(x), and atan(x), and atan2(y,x). atan2(y,x) evaluates tan(y/x) except the result is in the proper quadrant.
• conversion between radians and degrees: toDegrees(x) and toRadians(x)
• Hyperbolic functions: sinh(x), cosh(x), and tanh(x).
• logs and exponentials: log(x), log10(x), exp(x) where log(x) uses base e, log10(x) uses base 10, and exp(x) is e to the x.
• powers: pow(x, y) which calculates x to the y, i.e. x ^ y.
• rounding: round(x), roundTo(x, num), floor(x) and ceil(x). round(x) rounds off x to the nearest integer. roundTo(x, num) rounds x to num decimal places where num less than 0 is permitted. For example, roundTo(12345.6,-2) = 12300. floor(x) rounds x to nearest integer less than or equal to x while ceil(x) rounds x to nearest integer greater than or equal to x.
• maximum and minimum: max(x, y) and min(x, y).
• random numbers: random( ) produces a pseudo random number greater than or equal to 0 and less than 1.
• a user defined function user(...) which can have 0 to 10 parameters.
• most of the remaining Java methods: expm1(x), IEEEremainder(x, y), log1p(x), rint(x), signum(x), and ulp(x). See the Java docs for their definitions.

"user": The user defined function

The buildFromInfix method allow the user to define a function with 0 to 10 parameters. Because of notational difficulties, the buildFromPrefix and buildFromPostfix methods only allow defining 1 parameter functions. The formats for the string defining the function are
prefix: define = user parameter prefixExpression
infix: define user(parameter list) = infixExpression
postfix: define parameter user postfixExpression =

For example using infix:

 try {
     evaluator.buildFromInfix("define user(a, b, x) = x * max(a, b)");
     evaluator.setX(10);
     evaluator.setY(20);
     evaluator.setValueOf('z', 30);
     evaluator.buildFromInfix("100000 + user(x, y, z)");
     double value = evaluator.evaluate();
 } catch (...) {
     ...
 }
 

The following examples compare defining a function in prefix, infix, and postfix:
prefix: define = user t * 10 t
infix: define user(t) = 10 * t
postfix: define t user 10 t * =

When a build method is used to define a function, the resulting tree is null and it returns null. The parameters follow the same notational rule as variables: one lower case letter. Once defined, the number of parameters is fixed (until user is redefined). The expression used in defining a function can use parameters, constants and any other variables and functions.

When the user function is defined using buildFromPrefix or buildFromPostfix, it must have exactly 1 parameter. However, once defined, the user function can be used in prefix, infix and postfix expressions no matter which of the build functions was used to define it. This is true independently of the number of parameters the function has. (See TrivialExample4.java.)

roundTo(x, num)

The roundTo(x, num) function was inspired by the fact that Java often prints doubles with many decimal places. For example, we might see something like 1.5999999999 or 1.600000003 as approximations for 1.6 after a series of calculations. The function was modeled after the ROUND(number, num_digits) function in Excel. 'num' is the number of decimal places to which x is rounded. If num < 0, then the number is rounded to the left of the decimal point. For example, roundTo(12345.6,-3) = 12000.

The roundTo function is available both when running ExprEvaluator and as a public static function in the EasyFormat class.

Converting between different "..fixes"

The toPrefix(), toInfix(U) and toPostfix() methods allow converting from one "..fix" to another after using any of the build... methods. toInfix() provides fully parenthesized output. (I.e. typically there are many unneeded pairs of parenthesis. For Example. x+y*z will be output as (x+(y*z)) .)

Calculation errors

Illegal calculations such as 1/0, log(-1) or sqrt(-1) will typically result in infinity, -infinity, or NaN as is normal in Java.

Revisions

Beta 3: Modified for more efficient evaluations by adding fields to the binary nodes to avoid having to repeatedly check for values, types, and so on. Also ignores leading (unary) + signs.

Beta 4.0: Modified to allow variables a, b, ..., z.

Beta 4.1: Added the public static function roundTo
Allow = sign as a right associative operator.
Added the function roundTo(x, numDecPlaces)
Changed the name of the class for ExpressionTree to ExprEvaluator
Implemented buildFromPrefix.

Beta 4.2: Added help messages for infix function and used EasyFormat.roundTo.

Beta 4.3: Added methods that were previously in the subclass GraphEvaluator2D.

Beta 4.4: Added many new functions.

Beta 4.5: Added user defined function (and report error method), added help for prefix and postfix.

Beta 5.0: Implemented the toInfix() method and added TrivialExample5 to test it.

Beta 6.0: Added roundTo(x, num) as a public static method so it can be used in ap or applet similar to the way Math.sqrt is used. It is actually the same as EasyFormat.roundTo(x, num).

Requires:

EasyFormat.java
DoubleScanner.java
ArrayPureStack.java
BinaryNode.java
ExprTree.java
PureStack.java

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	DELIMITERS The allowed delimiters (operators).
static java.lang.String	infixHelp ## infixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when infix expressions are used.
static java.lang.String	introHelp ## introHelp can be used as the first part of a help message in applications using ExprEvaluator.
static double	PI ## The number PI = 3.14159...
static java.lang.String	postfixHelp ## postfixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when postfix expressions are used.
static java.lang.String	prefixHelp ## prefixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when prefix expressions are used.
static java.lang.String	varHelp ## varHelp can be used as the middle part of a help message in those situations where all 26 variables can be used.
static java.lang.String	variables A String holding the 26 variables "a" to "z" allowed in Expression tree and 10 parameters allowed in the user function.

Constructor Summary

Constructors

Constructor and Description
ExprEvaluator() ## Initializes an ExprEvaluator object with an empty expression tree.

Method Summary

Modifier and Type	Method and Description
ExprTree	buildFromInfix(java.lang.String infix) ## Builds an expression tree given an infix string of tokens.
ExprTree	buildFromPostfix(java.lang.String postfix) ## Builds an expression tree given a postfix string of tokens.
ExprTree	buildFromPrefix(java.lang.String prefix) ## Builds an expression tree given a prefix string of tokens.
ExprTree	buildTree(java.lang.String s) Deprecated. Starting with beta 4.5, buildFromInfix returns the tree and should be used instead of buildTree.
static int	comparePrecedence(java.lang.String op1, java.lang.String op2) Compares precedence of two operators.
void	convertToRect(double r, double theta) ## Converts polar coordinates into rectangular coordinates.
void	debugMode(boolean debugging) Sets the debug mode in buildFromInfix.
void	displayStacks(boolean debug) Sets the display stack mode in buildFromInfix.
double	evaluate() ## Returns the value of a binary expression tree previously created by one of the build methods using the current values of the variables.
double	evaluate(double[] params) ## Returns the value of a binary expression tree previously created by one of the build methods using the supplied parameters.
double	evaluate(double t, double x, double y) ## Returns the value of a binary expression tree previously created by one of the build methods using the supplied values of t, x, and y and the current values of the other variables.
double	evaluate(ExprTree tree) ## Evaluates the specified tree using the current values for the variables 'a', 'b', ..., 'z'.
java.lang.String	getInputStr() ## Returns the last input string processed by buildFromPrefix, buildFromInfix, or buildFromPostfix methods.
double	getT() ## Gets the value of t.
java.lang.String	getUserFunction() ## Returns the current user function as a string.
double	getValueOf(char var) ## Gets the value of the variable var where var is 'a', 'b', ..., or 'z'.
double[]	getValues() ## Returns the array of 26 doubles corresponding to the the variables "a", "b", ..., or "z".
double	getX() ## Gets the value of x.
double	getY() ## Gets the value of y.
static boolean	isDouble(java.lang.String s) Determines if the string is an double.
static int	isFunction(java.lang.String s) Returns a number >= 0 if the string s is a function name.
boolean	isOperator(java.lang.String s) Determines if the string is an operator.
static int	numFuncParams(java.lang.String s) Returns the number of parameters if the string is a function name.
static int	precedence(java.lang.String operator) Determines the precedence of an operator.
static double	roundTo(double x, double num) ## roundTo(x, num) rounds x to num decimal places where num less than 0 is permitted.
void	setT(double value) ## Sets the value of t.
void	setValueOf(char var, double value) ## Sets the value of the specified variable ('a', 'b', ..., or 'z') to the specified value.
void	setValues(double[] values) ## Sets the value of all 26 variables.
void	setX(double value) ## Sets the value of x.
void	setY(double value) ## Sets the value of y.
java.lang.String	toInfix() ## Creates a fully parenthesized infix expression String.
java.lang.String	toPostfix() ## Creates a postfix expression from the expression tree.
java.lang.String	toPrefix() ## Creates a prefix expression from the expression tree.
java.lang.String	toString() Output the tree structure -- used in testing/debugging.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PI

public static double PI

## The number PI = 3.14159...

variables

public static final java.lang.String variables

A String holding the 26 variables "a" to "z" allowed in Expression tree and 10 parameters allowed in the user function. The parameters follow the variables. Parameter names are either unprintable or have strange values. they are (char)123, (char)124, ..., (char) 132. The parameters are stored in reverse order so the parameter represented by (char)123 is always the last parameter.

See Also:

Constant Field Values

DELIMITERS

public java.lang.String DELIMITERS

The allowed delimiters (operators).

introHelp

public static java.lang.String introHelp

## introHelp can be used as the first part of a help message in applications using ExprEvaluator. introHelp should be followed by varHelp (or equivalent modified for the application) and then infixHelp. They can be used in something like:

      ExprEvaluator.introHelp + ExprEvaluator.varHelp
          + ExprEvaluator.infixHelp

See Also:

varHelp, prefixHelp, infixHelp, postfixHelp

varHelp

public static java.lang.String varHelp

## varHelp can be used as the middle part of a help message in those situations where all 26 variables can be used. It would normally be immediately preceded infixHelp. In those situations where only a restricted subset of variables are allowed, use an appropriate substitute for this string listing those variables.

See Also:

introHelp, prefixHelp, infixHelp, postfixHelp

prefixHelp

public static java.lang.String prefixHelp

## prefixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when prefix expressions are used. It should be preceded by introHelp and varHelp or equivalent customized for a particular applications.

      ExprEvaluator.introHelp + ExprEvaluator.varHelp
          + ExprEvaluator.prefixHelp

See Also:

introHelp, varHelp

infixHelp

public static java.lang.String infixHelp

## infixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when infix expressions are used. It should be preceded by introHelp and varHelp or equivalent customized for a particular applications.

      ExprEvaluator.introHelp + ExprEvaluator.varHelp
          + ExprEvaluator.infixHelp

See Also:

introHelp, varHelp

postfixHelp

public static java.lang.String postfixHelp

## postfixHelp can be used in a help message that explains to the user what is allowed as input to the ExprEvaluator when postfix expressions are used. It should be preceded by introHelp and varHelp or equivalent customized for a particular applications.

      ExprEvaluator.introHelp + ExprEvaluator.varHelp
          + ExprEvaluator.postHelp

See Also:

introHelp, varHelp

Constructor Detail

ExprEvaluator

public ExprEvaluator()

## Initializes an ExprEvaluator object with an empty expression tree.

Method Detail

debugMode

public void debugMode(boolean debugging)

Sets the debug mode in buildFromInfix. Debug output is produced and sent to System.out if the private variable debugStacks is true. The output is only useful for debugging build and evaluate methods.

Parameters:

debugging - - sets the debug mode (true turns the mode on).

displayStacks

public void displayStacks(boolean debug)

Sets the display stack mode in buildFromInfix. Output is produced and sent to System.out if the mode is true. This output may be useful to demonstrate how buildFromInfix uses stacks or to help while debugging.

Parameters:

debug - - sets the display stack mode (true turns the mode on.

getX

public double getX()

## Gets the value of x.

Returns:

- the value of x used in the last call of evaluate.

See Also:

setX(double)

setX

public void setX(double value)

## Sets the value of x.

Parameters:

value - - the value of variable 'x'

See Also:

getX()

getY

public double getY()

## Gets the value of y.

Returns:

- the value of y used in the last call of evaluate.

See Also:

setY(double)

setY

public void setY(double value)

## Sets the value of y.

Parameters:

value - - the value of variable 'y'

See Also:

getY()

getT

public double getT()

## Gets the value of t.

Returns:

- the value of t used in the last call of evaluate.

See Also:

setT(double)

setT

public void setT(double value)

## Sets the value of t.

Parameters:

value - - the value of variable 't'

See Also:

getT()

getValueOf

public double getValueOf(char var)

## Gets the value of the variable var where var is 'a', 'b', ..., or 'z'.

Parameters:

var - - the variable name as a character.

Returns:

- the value of the specified variable. If the variable is outside the range of 'a', 'b', ..., 'z', NaN (Not a Number) is returned instead.

See Also:

setValueOf(char, double), getX(), getY(), getT()

setValueOf

public void setValueOf(char var,
                       double value)

## Sets the value of the specified variable ('a', 'b', ..., or 'z') to the specified value. The value is ignored if the character var is outside the specified range.

Parameters:

var - - a character in the range 'a' to 'z'. The name of one of the 26 variables.

value - - the value to which the variable is set.

See Also:

getValueOf(char), setX(double), setY(double), setT(double)

getValues

public double[] getValues()

## Returns the array of 26 doubles corresponding to the the variables "a", "b", ..., or "z". The value of "a" is stored in location 0, the value of "b" is stored in location 1 and so on.

Returns:

- an array containing the values of the 26 variables.

See Also:

setValues(double[])

setValues

public void setValues(double[] values)

## Sets the value of all 26 variables.

Parameters:

values - - an array of doubles with the 26 variable values. If the array has less than 26 values, only corresponding values are set. If array has more than 26 values, only the first 26 are used.

See Also:

getValues()

getInputStr

public java.lang.String getInputStr()

## Returns the last input string processed by buildFromPrefix, buildFromInfix, or buildFromPostfix methods.

Returns:

= the last input string.

getUserFunction

public java.lang.String getUserFunction()

## Returns the current user function as a string.

Returns:

The user function. It will be the empty string if the function has not been defined properly.

isDouble

public static boolean isDouble(java.lang.String s)

Determines if the string is an double. Numbers begin with a digit or a '.', "+", or "-". Strings beginning with a nondigit must be longer than one character. Values passing these tests are parsed to make sure they will convert to a double.

(Note: if the DoubleScanner is used, number tokens cannot begin with + or -.)

Returns:

true if the string is an operator, false otherwise.

isOperator

public boolean isOperator(java.lang.String s)

Determines if the string is an operator. Recognized operators are '(', ')', '+', '-', '*', '/', '^', '=', and ','. "," is allowed only in functions used in infix expressions.

Actually this routine should be called isDelimiter as it only recognizes the operators that can be used in expressions.

Returns:

true if the string is an operator, false otherwise.

isFunction

public static int isFunction(java.lang.String s)

Returns a number >= 0 if the string s is a function name. Returns -1 if it is not a function name. The value is the subscript of the function name in the array of function names.

Parameters:

s - - the string which will be tested.

Returns:

- the subscript of the function in the array of functions names or -1 if the string is not a function.

numFuncParams

public static int numFuncParams(java.lang.String s)

Returns the number of parameters if the string is a function name. See functions for a list of function names that will be recognized. Returns the number of parameters for the function or -1 if the string is not a function name.

Parameters:

s - - the string which will be tested.

Returns:

- the number of parameters if the string is the name of a function or -1 if the string is not a function.

precedence

public static int precedence(java.lang.String operator)

Determines the precedence of an operator.

Parameters:

operator - - the operator.

Returns:

the precedence of the operator.

comparePrecedence

public static int comparePrecedence(java.lang.String op1,
                                    java.lang.String op2)

Compares precedence of two operators.

Parameters:

op1 - the first operator.

op2 - the second operator.

Returns:

a negative number if op1 < op2, 0 if op1 = op2, or a positive number if op1 > op2. Special cases: if op1 = "op2" = "^" or op1 = op2 = "=" then it returns -1 to cause "^" and "=" to be right associative.

buildFromPrefix

public ExprTree buildFromPrefix(java.lang.String prefix)
                         throws java.lang.Exception

## Builds an expression tree given a prefix string of tokens. It can be used to define the user function with 1 parameter. Tokens may be nonnegative double numbers, constant, variable, function or operator "+", "-", "*", "/", "^", or "="

Examples of postfix functions:
sqrt 16 : (square root of 16)
* sqrt + ^4 2 ^ 3 2 100 : (square root(4^2 + 3^2) * 100)
toDegrees atan2 1 sqrt 3 : (atan2(1, sqrt(3)) converted to degrees)

The tree built from the prefix string is assigned to root.

Parameters:

prefix - the infix string to be processed.

Returns:

the expression tree that was built. This may be considered the "compiled" version of the expression.

Throws:

java.lang.Exception

buildFromInfix

public ExprTree buildFromInfix(java.lang.String infix)
                        throws java.lang.Exception

## Builds an expression tree given an infix string of tokens. I can be used to define the user function with 0 to 10 parameters. Tokens may be double numbers (optionally with leading "-" or "+") or an operator "+", "-", "*", "/", "^" (exponent) or the names of the variables "a", "b",... or "z", the constants PI or E, or a function name. Names are case sensitive.

The precedence of operators:

• ( ) (highest priority)
• functions
• ^
• leading + and - signs
• * and /
• + and - (binary operations)
• = (assignment) (lowest priority)

The tree built from the infix string is assigned to root.

Parameters:

infix - the infix string to be processed.

Returns:

the expression tree that was built. This may be considered the "compiled" version of the expression.

Throws:

java.lang.Exception - - if an identifier name is invalid or the expression is invalid.

buildTree

public ExprTree buildTree(java.lang.String s)
                   throws java.lang.Exception

Deprecated. Starting with beta 4.5, buildFromInfix returns the tree and should be used instead of buildTree.

## Builds an ExprTree from the infix expression s and returns the tree. This is a simple extension of ExprEvaluator.buildFromInfix(s) which is used to build the tree but then extension returns the root of the ExprTree generated. This is useful if a situation requires evaluating more than 1 expression.

Parameters:

s - - the infix string to be processed.

Returns:

- the root of the tree generated.

Throws:

- - Exception - if an identifier name, a value, or the expression is invalid.

java.lang.Exception

buildFromPostfix

public ExprTree buildFromPostfix(java.lang.String postfix)
                          throws java.lang.Exception

## Builds an expression tree given a postfix string of tokens. It can be used to define the user function with 1 paramter. Tokens may be double numbers (leading + or - are not allowed) or an operator "+", "-", "*", "/", "^", or the name of a variable ("a", "b",..., "z"), a constant (PI or E), or a function name.

Examples of postfix functions:
16 sqrt : (square root of 16)
4 2 ^ 3 2 ^ + sqrt 100 * : (sq root(4^2 + 3^2) * 100)
1 3 sqrt atan2 toDegrees : (atan2(1, sqrt(3)) converted to degrees)

The tree built from the postfix string is assigned to root.

Parameters:

postfix - the postfix string to be processed.

Returns:

the expression tree that was built. This may be considered the "compiled" version of the expression.

Throws:

java.lang.Exception

toPrefix

public java.lang.String toPrefix()

## Creates a prefix expression from the expression tree.

Returns:

The string holding the expression written in postfix.

toInfix

public java.lang.String toInfix()

## Creates a fully parenthesized infix expression String.

Returns:

The string holding the expression written in infix.

toPostfix

public java.lang.String toPostfix()

## Creates a postfix expression from the expression tree.

Returns:

The string holding the expression written in postfix.

evaluate

public double evaluate()
                throws java.lang.Exception

## Returns the value of a binary expression tree previously created by one of the build methods using the current values of the variables. Once a binary tree is created by a build method, evaluate can be called repeatedly with different parameters.

In the case of illegal calculations such as 1/0, log(-1), or sqrt(-1), the result will typically be infinity, -infinity, or NaN (Not a Number). Note: This version assumes the values of the 26 values are unchanged from the last evaluation or the time they were supplied. If they have never been defined, their value will be 0.

Returns:

The value of the expression.

Throws:

java.lang.Exception - - if a function cannot be evaluated or has the wrong number of parameters.

See Also:

setT(double), setX(double), setY(double), setValueOf(char, double), setValues(double[])

evaluate

public double evaluate(double t,
                       double x,
                       double y)
                throws java.lang.Exception

## Returns the value of a binary expression tree previously created by one of the build methods using the supplied values of t, x, and y and the current values of the other variables. Once a binary tree is created by a build method, evaluate can be called repeatedly with different parameters.

In the case of illegal calculations such as 1/0, log(-1), or sqrt(-1), the result will typically be infinity, -infinity, or NaN (Not a Number).

Note: This version allows setting the values of the variables "t", "x", and "y". This may be completely adequate for many situations. The values of the other 23 variables are unchanged from any previous evaluations. If they have never been defined, there value will be 0.

Parameters:

t - - value of variable t.

x - - value of variable x.

y - - value of variable y.

Returns:

The value of the expression.

Throws:

java.lang.Exception - - if a function cannot be evaluated or has the wrong number of parameters.

evaluate

public double evaluate(double[] params)
                throws java.lang.Exception

## Returns the value of a binary expression tree previously created by one of the build methods using the supplied parameters. Once a binary tree is created by a build method, evaluate can be called repeatedly with different parameters.

In the case of illegal calculations such as 1/0, log(-1), or sqrt(-1), the result will typically be infinity, -infinity, or NaN (Not a Number).

In this version of evaluate, the values of all 26 variables are supplied in an array.

Parameters:

params - - an array of 26 double values corresponding to the values of variables "a", "b", ..., "z"

Returns:

The value of the expression.

Throws:

java.lang.Exception - - if a function cannot be evaluated or has the wrong number of parameters.

See Also:

getValues()

evaluate

public double evaluate(ExprTree tree)
                throws java.lang.Exception

## Evaluates the specified tree using the current values for the variables 'a', 'b', ..., 'z'. (This is a simple extension of ExprEvaluator.evaluate().

Use set... functions to assign values to variables before calling this methods.

Parameters:

tree - - the ExprTree to be evaluated.

Returns:

- the value of the expression which generated the ExprTree.

Throws:

java.lang.Exception - - if a function cannot be evaluated or has the wrong number of parameters.

See Also:

setX(double), setY(double), setT(double), setValueOf(char, double), setValues(double[]), evaluate()

convertToRect

public void convertToRect(double r,
                          double theta)

## Converts polar coordinates into rectangular coordinates. The results are stored in the variables "x" and "y". The other 24 variables remain unchanged. The getX and getY methods can be used to retrieve the values.

Parameters:

r - - the radius in polar coordinates.

theta - - the angle in polar coordinates. It is measured in radians.

See Also:

getX(), getY(), getValueOf(char)

toString

public java.lang.String toString()

Output the tree structure -- used in testing/debugging. Source: A modification of showStructure() in Data Structures *** in C++ by Roberge.

Overrides:

toString in class java.lang.Object

Returns:

String repression of the expression tree.

roundTo

public static double roundTo(double x,
                             double num)

## roundTo(x, num) rounds x to num decimal places where num less than 0 is permitted. For example, roundTo(12345.6,-2) = 12300. It is the same as EasyFormat.roundTo. For output, consider EasyFormat.format(double x, int num) instead which produces a string instead of a double.