Variables

Basics

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.

top

Undeclared and undefined variables

During parsing, the parser looks up whether variables exists. The Jep.setAllowUndeclared(boolean flag) sets the behaviour for undeclared variables:

  1. Allow undeclared variables (default): undeclared variables will be added to the VariableTable while parsing an expression.
  2. Do not allow undeclared variables: In this case it is necessary to add a variable using 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.

top

Constants

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.

top

Assignment

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) {}
top

Obtaining a list of variables

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.

top

Observers for variables

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.

top