1 Introduction

GNU libmatheval is library comprising several procedures that makes possible to create in-memory tree representation of mathematical functions over single or multiple variables and later use this representation to evaluate function for specified variable values, to create corresponding tree for function derivative over specified variable or to get back textual representation of in-memory tree.

This section discuss use of programming interface exposed by library from C programs. Readers interested in Fortran interface should switch immediately to Fortran interface section.

In order to use GNU libmatheval library from C code, it is necessary first to include header file matheval.h from all files calling GNU libmatheval procedures and then refer to libmatheval library among other linker option. Thus, command to compile C program using library and stored in file example.c using GNU C compiler would look like (supposing that library is installed using default prefix /usr/local/lib):

gcc example.c -I/usr/local/include -L/usr/local/lib -lmatheval -o example

Alternatively, pkg-config metadata file for libmatheval is installed along with the library too, thus on system with pkg-config installed following command could be used instead:

gcc example.c $(pkg-config --cflags --libs) -o example

First step in actually utilizing library after including appropriate header file would be to declare variable of void * type to point to evaluator object that will represent given mathematical function:

void *f;

Then, given that textual representation of function is stored into string buffer, evaluator object corresponding to given mathematical function could be created using evaluator_create procedure (see evaluator_create) as follows (see documentation for this procedure also for description of notation that should be used to describe mathematical functions):

f = evaluator_create (buffer);
assert (f);

Return value should be always checked, because above procedure will return null pointer if there exist syntax errors in notation. After that, one could utilize evaluator_get_variables (see evaluator_get_variables) procedure to obtain a list of variable names appearing in function:

{
  char **names;
  int count;
  int i;

  evaluator_get_variables (f, &names, &count);
  for (i = 0; i < count; i++)
    printf ("%s ", names[i]);
  printf ("\n");
}

Procedure evaluator_evaluate (see evaluator_evaluate) could be used to evaluate function for specific variable values. Say that above function is over variable “x” only, then following code will evaluate and print function value for x = 0.1:

{
  char *names[] = { "x" };
  double values[] = { 0.1 };

  printf ("f(0.1) = %g\n", evaluator_evaluate (f, 1, names, 
                                               values));
}

Or alternatively, since function is over variable with standard name “x”, convenience procedure evaluator_evaluate_x (evaluator_evaluate_x) could be used to accomplish same by following:

printf ("f(0.1) = %g\n", evaluator_evaluate_x (f, 0.1));

Evaluator object for function derivative over some variable could be created from evaluator object for given function. In order to accomplish this, a declaration for derivative evaluator object should be added to variable declarations section:

void *f_prim;

After that (supposing that “x” is used as derivation variable), derivative evaluator object could be created using evaluator_derivative procedure (see evaluator_derivative):

f_prim = evaluator_derivative (f, "x");

or alternatively using evaluator_derivative_x convenience procedure (see evaluator_derivative_x):

f_prim = evaluator_derivative_x (f);

Derivative evaluator object could be used to evaluate derivative values or say textual representation of derivative could be written to standard output through utilizing evaluator_get_string procedure (see evaluator_get_string) to get string representing given evaluator. Following code would accomplish this:

printf ("  f'(x) = %s\n", evaluator_get_string (f_prim));

All evaluator objects must be destroyed after finished with using them and evaluator_destroy procedure (see evaluator_destroy) is intended for this:

evaluator_destroy (f);
evaluator_destroy (f_prim);

Here follows complete program connecting above fragments. Program read from standard input string representing function over variable “x”, create evaluators for function and its first derivative, print textual representation of function derivative to standard output, then read value of variable “x” and finally print to standard output values of function and its first derivative for given value of variable “x”.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <matheval.h>

/* Size of input buffer.  */
#define BUFFER_SIZE 256

/* Program is demonstrating use of GNU libmatheval library of procedures
   for evaluating mathematical functions.  */
int
main (int argc, char **argv)
{
  char buffer[BUFFER_SIZE];	/* Input buffer.  */
  int length;			/* Length of above buffer. */
  void *f, *f_prim;		/* Evaluators for function and function derivative.  */
  char **names;			/* Function variables names. */
  int count;			/* Number of function variables. */
  double x;			/* Variable x value.  */
  int i;			/* Loop counter. */

  /* Read function.  Function has to be over variable x, or result may
     be undetermined.  Size of textual represenatation of function is
     bounded here to 256 characters, in real conditions one should
     probably use GNU readline() instead of fgets() to overcome this
     limit.  */
  printf ("f(x) = ");
  fgets (buffer, BUFFER_SIZE, stdin);
  length = strlen (buffer);
  if (length > 0 && buffer[length - 1] == '\n')
    buffer[length - 1] = '\0';

  /* Create evaluator for function.  */
  f = evaluator_create (buffer);
  assert (f);

  /* Print variable names appearing in function. */
  evaluator_get_variables (f, &names, &count);
  printf ("  ");
  for (i = 0; i < count; i++)
    printf ("%s ", names[i]);
  printf ("\n");

  /* Create evaluator for function derivative and print textual
     representation of derivative.  */
  f_prim = evaluator_derivative_x (f);
  printf ("  f'(x) = %s\n", evaluator_get_string (f_prim));

  /* Read variable x value.  */
  printf ("x = ");
  scanf ("%lf", &x);

  /* Calculate and print values of function and its derivative for given
     value of x.  */
  printf ("  f(%g) = %g\n", x, evaluator_evaluate_x (f, x));
  printf ("  f'(%g) = %g\n", x, evaluator_evaluate_x (f_prim, x));

  /* Destroy evaluators.  */
  evaluator_destroy (f);
  evaluator_destroy (f_prim);

  exit (EXIT_SUCCESS);
}

Above example exercise most of library main procedures (see Main entry points), as well as some of convenience procedures (see Convenience procedures). For full documentation, see Reference.