Variables are represented by the Variable class and stored in a VariableTable. The value of a variable can be set using
Jep.addVariable(String name,Object val)
and retrieved with
Object Jep.getVariableValue(String name)
The addVariable()
method can also be used to change the value of existing variables.
For double
values, use
the Jep.addVariable(String, double)
method and for complex numbers, use the
Jep.addVariable(String, double, double)
method.
A further method, getVariable(String),
returns the Variable object. This class allows variables to be observed and offers a marginally faster method for getting and setting variable values.
During parsing, the parser looks up whether variables exists. The Jep.setAllowUndeclared(boolean flag) sets the behaviour for undeclared variables:
addVariable()
methods before parsing.
A ParseException will be thrown if an undeclared variable is encountered. This option is useful
if you wish to restrict the variables which can appear in an expression.
During evaluation the value of a variable will be retrieved. If the value is undefined
(null
),
then an EvaluationException will be thrown. Null values will occur if the variable values have not
been set using addVariable()
. In particular this will occur if allowUndeclared
is true
and a variable is created while parsing. This behaviour can be changed
by calling the
StandardEvaluator.setTrapNullValues(boolean flag)
method.
The Jep.setDefaultValue(Object)
method can be used to set the default value variables.
Variables can be defined as being constants, whos values is fixed. By default Jep defines the constants
e
(2.718281828459045),
pi
(3.141592653589793),
i
(Complex number i) and boolean constants true
and false
.
To add a constant use
jep.addConstant("tau", (1+Math.sqrt(5))/2.);
To remove a constant use
jep.getVariableTable().remove("e");
To initilise Jep with no constants use the VariableTable component
Jep jep = new Jep(new VariableTable());
Individual variables have an isConstant field, which can be accessed via the isConstant()
method and set via setIsConstant(boolean b)
.
If the field is set then variable value cannot be changed.
Assignment allows the values of variables to be set by using the =
operator in equations so it is possible to assign values with expressions
like
x = 3
then use the assigned values in an expression such as
y = x^2
and y
will have the value 9. Assignment is enabled by default. To disable assignment facilities, the setAllowAssignment(boolean)
method of the main Jep object should be called. Calling setAllowUndeclared(true)
is required for Jep to parse the assignment equations.
Important: It is necessary to call the evaluate() method after parsing for the variable value to be assigned.
// standard initialisation
Jep j = new Jep();
j.setAllowUndeclared(true);
// switch assignment facilities on
j.setAllowAssignment(true);
// parse assignment equations
try {j.parse("x=3");} catch (ParseException e) {}
// evaluate it - no need to save the value returned
try {j.evaluate();} catch (EvaluationException e) {}
// parse a second equation
try {j.parse("y=2");} catch (ParseException e) {} try {j.evaluate();} catch (EvaluationException e) {}
// an equation involving the above variables try {j.parse("x^y");} catch (ParseException e) {}
try { Object val3 = j.evaluate(); System.out.println("Value is " + val3); } catch (EvaluationException e) {}
If you parse an expression with an unknown set of variables (when the allowUndeclared option is enabled), you may need to know which variables occurred in the expression. There are two ways of obtaining a list of the variables.
One approach is to use the getVariableTable method. With the returned variable table you can then check its contents to see which variables have been added while parsing.
In particular the VariableTable.getVariables() returns a list of
all variables. The VariableTable's toString()
will produce a printable list.
The second approach is to use the TreeAnalyzer class to examine an expression tree after parsing an expression. See the JavaDoc documentation for more information on how to use it.
The Variable class implements the Observer/Observable pattern.
This allows objects to be informed whenever variable values change. To register a class as an observer of a variable, use the Variable.addObserver(Observer)
methods.
The VariableTable can also be observed to check for the addition of new variables, see
VariableTableObserver
for a class to facilitate observing the VariableTable and its Variables.