The EXPRINT library — API documentation

TMC Suite package. A static interpreter library for string mathematical expressions (parsing and evaluation of formulas). All signatures are taken from the sources in src/libs/Expr/, src/libs/Inter/ and the shared headers from src/Include/.

1. Purpose of the library

EXPRINT is a static library that implements an interpreter of string mathematical expressions (a formula evaluator).

The library takes as input a formula as a text string (for example, "sin(x)+2*y", "return(A^2)", "if(x-1) y=5") and returns its numeric value of type _real. Supported:

• arithmetic: = (assignment), +, -, *, /, ^ (power);
• grouping parentheses ( ) and block braces { };
• built-in elementary functions: abs, exp, log, log10, sin, cos, tan, sqrt, sinh, cosh, tanh, asin, acos, atan;
• variables — a single Latin letter A–Z / a–z (an array of 256 cells, indexed by the character code);
• interpreter control operators: return(...), if(...) ..., while(...) ...;
• a choice of angle units for trigonometry (radians or degrees).

The library is logically divided into two modules:

• The Expr module (src/libs/Expr/) — the arithmetic core: lexical parsing, expression evaluation, functions, variables, error-code handling.
• The Inter module (src/libs/Inter/) — the interpreter add-on: the return/if/while operators, splitting a string into a sequence of operators, whitespace cleanup.

The library is used in the package's viewers (the CTMCGrExpression class — it is not part of EXPRINT and is documented as part of the viewers) to build custom graphs from entered formulas.

Origin: TAMIC_soft(R), 25.10.1991, v2.00 — historical code for DOS / win16, ported to TMC Suite.

About the _far, fortran macros. These are legacy memory-model and calling-convention attributes from 16-bit code (Microsoft C / early Visual C++). In the header INTER.H a number of prototypes are declared as _real _far fortran inte_atof(...). In the modern 32/64-bit build these macros usually expand to nothing and do not affect the semantics. For brevity they are omitted from the signatures below (a "clean" prototype is given). See EXPR.H / INTER.H for the full prototypes.

About the _real type. The _real type is defined in the external header typedef.h and, depending on the build, corresponds to float or double. All of the library's computations and return values are of type _real.

2. Location of the sources

Important: the directory src/libs/exprint/ contains only project files (exprint.vcxproj, etc.). There is no actual source code in it. The exprint.vcxproj project references the sources through the relative paths ..\Expr\ and ..\Inter\.

The Expr module — src/libs/Expr/

The Inter module — src/libs/Inter/

Headers — src/Include/

Files outside the build (not documented)

• DRV_EXPR.CPP, DRV_INTE.CPP — test console drivers (contain main, implement an interactive calculator). Not part of the EXPRINT build.
• Expr.rar — an archive, not unpacked; its contents are unknown.

3. Structures, types and constants

3.1. INTE_OPER (INTER.H)

The description of one interpreter-operator keyword (name + length).

typedef struct {
    char lpszName[32];   // the operator keyword name, e.g. "return("
    int  nLenght;        // the length of the keyword (number of characters)
} INTE_OPER;

In Inte_ope.cpp a static array of these structures is defined:

INTE_OPER lpsOper[] = {
    { "return(", 7 },
    { "if(",     3 },
    { "while(",  6 },
};

3.2. Built-in function codes (EXPR.H)

The numeric codes of the functions passed into expr_comp (see section 4.1 and the grammar in section 5).

3.3. Angle-mode constants (EXPR.H)

3.4. Other constants (EXPR.H)

3.5. The internal state of the modules

The library stores several global static variables (not exported directly, accessible through functions):

4. Public functions

Summary table

4.1. The Expr module (arithmetic)

void expr_set_angle(int flag)

File: Expr_com.cpp.

Sets the angle units for the trigonometric functions.

• Parameters:
• flag (int) — EXPR_GRADUS (0) → degrees (expr_angle = PI/180); any other value, in particular EXPR_RADIAN (1) → radians (expr_angle = 1.0).
• Return: none.
• Effect: the expr_angle factor is applied inside expr_comp: for sin/cos/tan the argument is multiplied by expr_angle; for asin/acos/atan the result is divided by expr_angle.
• Default: degrees (expr_angle = PI/180).

_real expr_comp(int cod, char *oper1, int n1, char *oper2, int n2)

File: Expr_com.cpp.

Performs one operation or function cod on the operands given as strings. The operands are first recursively evaluated via expr_inter.

• Parameters:
• cod (int) — the operation code. It can be the character of an arithmetic operator ('=', '+', '-', '*', '/', '^' — in fact the ASCII code of the character) or a numeric function code (ABS…LOG10, see section 3.2).
• oper1 (char*) — the string of the first operand (for functions — its argument);
• n1 (int) — the length of oper1; if 0, then op1 = 0;
• oper2 (char*) — the string of the second operand (used only for binary operators, for which cod > LOG10);
• n2 (int) — the length of oper2; if 0 for a binary operator, ERROR_EXPRESSION is set.
• Return: the result of the operation (_real).
• Features and errors (by cod):
• if a non-zero error code is already set on input — the function immediately returns 0;
• '=' — assignment: oper1 must be a variable name (expr_is_per), otherwise ERROR_VAR and a return of 0; otherwise the value op2 is written into the variable and returned;
• '^' — power: requires op1 > 0, otherwise ERROR_POW; when op2 > |log(FLT_MAX)/log(op1)| → ERROR_OVERFLOW, return FLT_MAX;
• '+', '-', '*' — arithmetic; when the result is > FLT_MAX → ERROR_OVERFLOW, return FLT_MAX;
• '/' — division: when op2 == 0 → ERROR_DIV_0, return FLT_MAX; on overflow → ERROR_OVERFLOW;
• the functions EXP, LOG, SIN, COS, TAN, ABS, SQRT, SINH, COSH, TANH, ASIN, ACOS, ATAN, LOG10 — see the checks table in section 5.5;
• default (an unknown code) → the error code -cod is set, return 0.

void expr_set_error_cod(int n)

File: Expr_err.cpp.

Sets the global parse error code.

• Parameters: n (int) — the error code (0 — no error; negative values — see section 6).
• Return: none.

int expr_get_error_cod(void)

File: Expr_err.cpp.

Returns the current global error code.

• Parameters: none.
• Return: the error code (int). 0 — no errors.

_real expr_atof(char *string)

File: Expr_in1.cpp.

Evaluates a whole arithmetic expression. Resets the error code to 0 and delegates the parsing to expr_inter.

• Parameters: string (char*) — the expression string (without support for the return/if/while operators — for those inte_atof is used).
• Return: the value of the expression (_real). On error, see expr_get_error_cod().
• Note: the function name (atof) is historical — it is a full expression parse, not just a number conversion.

_real expr_inter(char *lex, int n)

File: Expr_in1.cpp.

Recursive parsing and evaluation of a substring lex of length n. The core of the arithmetic interpreter.

• Parameters:
• lex (char*) — the buffer of the expression string (the function temporarily modifies the character lex[n], substituting '\0', then restores it — the buffer must allow writing at index n);
• n (int) — the length of the substring being parsed.
• Return: the value of the substring (_real).
• Algorithm (briefly): 1. if there is already an error — return 0; 2. if the substring is a numeric literal (expr_numbern), it is computed via atof (when > FLT_MAX → ERROR_OVERFLOW); 3. if the substring is a variable name (expr_is_per), its value is returned; 4. the search for a top-level binary operator in the priority order of the string arif[] = "=+-*/^" (taking into account the nesting of () and {}); when found — a call of expr_comp; 5. if the string is entirely enclosed in ( ) — recursion over the inner part; 6. recognition of a function name (abs(…log10() and a call of expr_comp; 7. otherwise — ERROR_FUNCTION.
• Errors: ERROR_BRACKET (unbalanced parentheses), ERROR_FUNCTION (an unrecognized construct), ERROR_OVERFLOW.

int expr_numbern(char *lex, int n)

File: Expr_in1.cpp.

Checks whether the string lex (of length n) is a valid numeric literal.

• Parameters:
• lex (char*) — the string;
• n (int) — the length.
• Return:
• 0 — the string is a number;
• 1 — it is not a number.
• Supported format: a leading - sign, digits, one decimal point, an exponent of the form e+/e-. The literal length is limited: when n > 40, 1 is returned immediately.

_real expr_get_per(char *lpszName, int nLenghtName)

File: Expr_per.cpp.

Returns the value of a variable.

• Parameters:
• lpszName (char*) — the variable name; only the first character lpszName[0] is used as the index in the array rExpr_per[256];
• nLenghtName (int) — the name length (in fact ignored in the function body).
• Return: the variable value (_real).

void expr_set_per(char *lpszName, int nLenghtName, _real rValue)

File: Expr_per.cpp.

Sets the value of a variable.

• Parameters:
• lpszName (char*) — the variable name; only the first character is used as the index in rExpr_per[256];
• nLenghtName (int) — the name length (ignored in the body);
• rValue (_real) — the value to write.
• Return: none.

int expr_is_per(char *lpszName, int nLenghtName)

File: Expr_per.cpp.

Checks whether a string is a variable name (exactly one character — a Latin letter).

• Parameters:
• lpszName (char*) — the string being checked;
• nLenghtName (int) — the string length; must equal 1.
• Return:
• 0 — it is a variable name (length 1 and a character from A–Z or a–z);
• -1 — it is not a variable name.

char* expr_get_error(void)

File: Expremsg.cpp.

Returns a text (English) description of the current error.

• Parameters: none.
• Return: a pointer to a string from the static array char_error[]. The index is computed as -expr_get_error_cod(). The array contains 23 elements (indices 0…22), see section 6.
• Caution: the function does not check the range. A correct result is obtained only for the error codes 0 and -1…-22. Other values will lead to an out-of-bounds access.

int get_expr_err(char *lpszExpr)

File: Get_err.cpp.

Converts an internal error code into a common project code (the range 2400+).

• Parameters: lpszExpr (char*) — the expression string (passed for a possible message output; the put_error_messege call is commented out in the current build).
• Return:
• 0 — if there are no errors (nTmp == 0);
• -nTmp, where nTmp = -error_cod, when nTmp > 20 it is capped at 21, then += 2400. The resulting project codes: 2401…2421 (returned with a minus sign, i.e. -2401…-2421).
• The correspondence of the internal codes to the project codes — see section 6.

4.2. The Inter module (the return / if / while operators)

_real inte_atof(char *string)

File: Inte_in1.cpp.

Evaluates an expression or a sequence of operators of the interpreter. The entry point for formulas with return/if/while.

• Parameters: string (char*) — the string (the buffer must allow modification at the length index — see inte_inter/expr_inter).
• Return: the value (_real).
• Logic: resets the error code to 0, evaluates via inte_inter. If on completion ERROR_RETURN is set — the saved value inte_get_inter_value() is returned, and the error code is reset to 0 (that is, return is treated as a normal completion).

_real inte_inter(char *lex, int n)

File: Inte_in1.cpp.

The top-level interpreter. Splits the string into a sequence of operators and evaluates them in order.

• Parameters:
• lex (char*) — the string buffer;
• n (int) — the length.
• Return: the value (_real).
• Algorithm: 1. if there is an error — return 0; an empty string or a single ; — return 0; 2. if the string is entirely in the block braces { } — recursion over the inner part; 3. the search for the operator separator — a top-level ; character (taking into account the nesting of {} and ()); when found — the sequential evaluation of the left and right parts (the result of the right one is returned); 4. on unbalanced parentheses — ERROR_BRACKET; 5. an attempt to evaluate as an arithmetic expression via expr_inter; on success — return the result; if the error is not ERROR_FUNCTION — return 0; 6. otherwise an attempt to recognize an operator via inte_oper; with code 0 or ERROR_RETURN — return the result; 7. otherwise — ERROR_FUNCTION.
• The operator separator: the ; character (INTER_BLANCK) at the top nesting level.

int i1nte_atof_1(char *string, double *r)

File: Inte_in1.cpp.

Removes whitespace characters from the string and evaluates it; the result is returned through a pointer.

• Parameters:
• string (char*) — the string (modified in-place by the expr_del_Blanks1 function);
• r (double*) — output: the computed value.
• Return: the error code (int) — the result of expr_get_error_cod() after evaluation (0 — success).
• Logic: expr_del_Blanks1(string) → *r = inte_atof(string) → return the error code.

int expr_del_Blanks1(char *ch)

File: Inte_in1.cpp.

Removes from the string (in-place) all spaces, tabs and newlines.

• Parameters: ch (char*) — the string (modified in place; the terminating '\0' is kept).
• Return: always 0.
• Removed characters: ' ' (space), '\t' (tab), '\n' (newline).

_real inte_oper(char *lex, int n)

File: Inte_ope.cpp.

Recognizes and executes one of the control operators: return(...), if(...) ..., while(...) ....

• Parameters:
• lex (char*) — the buffer of the operator string;
• n (int) — the length.
• Return: the value (_real).
• Behavior by operator:
• return(expr) — evaluates expr via inte_inter; in the absence of an error it sets ERROR_RETURN, saves the value via inte_set_inter_value and returns it;
• if(cond) stmt — finds the end of the condition (inte_select_blanck), evaluates cond; if cond < 0 the operator stmt is skipped (there is no else branch), cond is returned; otherwise stmt is evaluated and returned;
• while(cond) stmt — while cond >= 0: evaluates stmt, then re-evaluates cond; ends when cond < 0; on an error at any step — return 0;
• if no operator is recognized — ERROR_FUNCTION, return 0.

int inte_select_blanck(char *lex, int n)

File: Inte_ope.cpp.

Finds the position of the top-level closing parenthesis ) (the end of the operator condition), taking into account the nesting of () and {}.

• Parameters:
• lex (char*) — the string (starting right after the operator keyword);
• n (int) — the length.
• Return: the index of the top-level closing ) (or n if not found).
• Nesting accounting: depth counters for round () and curly {} brackets.

void inte_set_inter_value(_real r)

File: Inte_val.cpp.

Saves the value returned by the return operator.

• Parameters: r (_real) — the value to save.
• Return: none.

_real inte_get_inter_value(void)

File: Inte_val.cpp.

Returns the value previously saved by the return operator.

• Parameters: none.
• Return: the saved value (_real); 0 by default.

5. Expression grammar

5.1. Numbers

• Numeric literals: integers and fractions (a decimal point .), with an optional leading - sign.
• Exponential notation: e+ / e- (for example, 1.5e-3).
• Recognized by the expr_numbern function. The maximum literal length is 40 characters (beyond that — not treated as a number).

5.2. Variables

• A variable name is exactly one Latin character: A–Z or a–z.
• The values are stored in an array of 256 cells rExpr_per[256], indexed by the code of the first character of the name. Lowercase and uppercase letters are different variables (different codes).
• Reading — expr_get_per, writing — the = operator or expr_set_per, name check — expr_is_per.

5.3. Operators (the string arif[] = "=+-*/^")

Binary operators are searched for in the expression string from right to left, in the order of the elements of the arif string. The search is done only at the top level of nesting (taking () and {} into account).

5.4. Parentheses

• ( ) — grouping of arithmetic subexpressions. They must be balanced, otherwise ERROR_BRACKET.
• { } — block braces at the interpreter level (the body of if/while operators, operator grouping). Taken into account when searching for separators and closing brackets.

5.5. Built-in functions

A function name is written with a parenthesis, for example sin(x). The argument is evaluated recursively. The angle mode (see expr_set_angle) affects trigonometry.

5.6. Interpreter operators (the Inter module)

The operator separator in a sequence is the ; character at the top level (see the note in inte_inter).

5.7. The angle mode

The trigonometric functions and their inverses take into account the global factor expr_angle, set by expr_set_angle:

• degrees (by default): expr_angle = PI/180;
• radians: expr_angle = 1.0.

For the direct functions (sin/cos/tan) the argument is multiplied by expr_angle; for the inverses (asin/acos/atan) the result is divided by expr_angle.

6. Parse error codes

6.1. Internal codes (EXPR.H)

The internal error codes are negative integers. They are stored in error_cod (Expr_err.cpp).

Note the shift: the texts in char_error[] for indices 21 and 22 are shifted relative to the meaning of the codes (ERROR_RETURN = -21 corresponds to the text "bad parameter in =", and ERROR_VAR = -22 to the text "bad return"). This is a peculiarity of the source array in Expremsg.cpp (the array contains 23 elements, indices 0…22). The messages are in English.

6.2. Mapping to project codes (2401…2421) via get_expr_err

The get_expr_err function (Get_err.cpp) converts an internal code into a common project code:

int nTmp = -expr_get_error_cod();   // 0..22
if (nTmp == 0) return 0;            // no errors
if (nTmp > 20) nTmp = 21;          // all codes > 20 collapse into 21
nTmp += 2400;                       // 2401..2421
return -nTmp;                       // returned with a minus sign

The project codes ERROR_EXPR_* (2401…2420) are defined in Error1.h.

7. Dependencies

Shared headers (src/Include/):

Standard C/C++ headers: math.h, float.h, stdio.h, stdlib.h, string.h, conio.h.

Relation to other TMC Suite libraries:

• EXPRINT does not use the complex library directly — only the scalar _real type is involved.
• No direct #includes from SFILE95, TMCLibError, PREPR, TMCIndan were found in the EXPRINT sources.