Basic Usage

Getting started

Using the Jep.Net package of classes in your project is simple! The following steps will get you started quickly.

  1. Download the Jep.Net package
  2. Unpack the archive
  3. Move the jep.dll file (located in the main directory) to a directory of your choice
  4. IMPORTANT: For the compiler to be able to find the Jep.Net classes when compiling your program, it needs to know their location. You will need to set the location of the dll in your IDE so that the compiler finds the library (refer to your IDE manual for how to do this). If you are not using an IDE, will need to add the location of the Jep.dll file to the command line compile instruction with " /r:Jep.dll" (be sure to use the correct path to Jep.dll).
  5. Include the following code in your program
    using SingularSys.Jep;
     1: JepInstance jep = new JepInstance();
     2: jep.AddVariable("x",10);
     3: try {
     4:     jep.Parse("x+1");
     5:     Object result = jep.Evaluate();
     6:     Console.Out.WriteLine("x + 1 = " + result);
     7:     Console.ReadKey(true);
     8: } catch (JepException e) {
     9:     Console.Out.WriteLine("An error occured: " + e.Message);
    10: }
    11: Console.ReadKey(true);
    Line 1 creates a new Jep parser object (Class description). Line 2 adds the variable "x" to the parser and initializes it's value to 10. In lines 4 and 5, the expression "x+1" is parsed and evaluated. The result is stored in result. Finally, the result, "x + 1 = 11", is printed to the Console.
  6. You should be able to compile your application and see the result printed when you run your program.

What's next? Browse through the documentation to see what Jep.Net is all capable of. Also have a look at the code of the sample program. And don't forget to use the Code Documentation as handy reference!


Handling errors

Exceptions are thrown by the parse and evaluate methods if an error occurs. Parsing methods throw ParseException instances while evaluation methods throw EvaluationException instances. Both of these classes extend the JepException class. So if you do not need to distinguish between parsing and evaluation errors, simply catch JepException instead.

The exception classes provide information about the error that occured through the Message property.


Default setup

If you create a Jep instance with default settings you can parse expressions with the all functions listed in the Functions section. You can also use the following constants:

pi 3.1415... The ratio of the circumference of a circle to its diameter (Math.PI )
e 2.718... Euler's constant in double precision (Math.E)
true The boolean constant (true)
false The boolean constant (false)
i The complex imaginary unit


Evaluation methods

Three methods for evaluating an expression are available:

You may not always know what type the result of the expression is. For example it could be Double, Array, Boolean, or String depending on the expression parsed. You can use the is operator to identify the type of the result, then cast the result into the appropriate class.


Fast evaluation using RealEvaluator

If you want to speed up your calculations, and you are not using strings, arrays or complex numbers, you can use the RealEvaluator instead of the StandardEvaluator. Evaluation is sped up by using only the primitive double type rather than creating Double objects. Load the RealEvaluator by setting the Evaluator property as shown below.

using SingularSys.Jep.Reals;
jep.Evaluator = new RealEvaluator();

Fast repeated evaluation

It is possible to perform repeated evaluation of expressions while changing variable values without repeatedly parsing the expression. This, of course, is much faster than re-parsing the expression each time it needs to be evaluated.

The following code shows how the AddVariable(String, Object) and Evaluate() functions can be called repeatedly to change variable values and re-evaluate an expression.

  // add variable to allow parsing
  jep.AddVariable("x", 0);
  // evaluate expression for x = 0 to x = 99
  for (int i=0; i<100; i++) {
      // update the value of x
      jep.AddVariable("x", i);
      // print the result
      Console.Out.WriteLine("Value at x = " + i + ": " + jep.Evaluate());

You can use fast repeated evaluation with any evaluator including the RealEvaluator.


Implicit multiplication

You can disable the implicit multiplication option with jep.ImplicitMul = false;. The default setting is true (implicit multiplication is active).Implicit multiplication allows expressions such as "2x" to be interpreted as "2*x".

Note that a space is required between two variables for them to be interpreted as being multiplied, for example "x y". The same holds for a variable followed by a number. For example "y 3" is interpreted as "y*3", but "y3" is interpreted as a single variable with the name y3. If a variable is preceded by a number, no space is required between them for implicit multiplication to come in effect.