Introduction

Matheval v1.65

by Matt Lewis
matthewwalkerlewis@gmail.com
http://www14.brinkster.com/matthewlewis

What is matheval?

Matheval is a library designed for evaluating mathematical expressions. It can parse an expression from clear text and convert into its internal format. (See Expressions for more detail.) My inspiriation for creating matheval comes from such packages as Maple or Mathematica. I wanted to be able to do some of those sorts of things from within Euphoria.

Matheval will do some symbolic evaluation, including simplifying algebraic expressions. Variables can be created and can hold any value, including entire expressions, so some very powerful tasks can be accomplished using matheval. The library has also been designed to be flexible enough to be extended fairly easily.

Matheval can be used as a drop in component for an app that needs to do calculations based on user input, when the calculations themselves are not known until runtime. An example of this is what I've done in EuSQL. Matheval is used to do any math, text manipulation and the conditional checking needed in SQL WHERE clauses, which was why booleval.e was created. It allows EuSQL to evaluate a boolean expression of any complexity, without any foreknowledge of what the variables or values or conditions will be.

New as of v1.6, matheval has some scripting features, allowing more complex algorithms to be evaluated entirely within matheval.

Disclaimer: ************************************************************************** This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you or your computer. Use it at your own risk.

You are free to use and or modify the source code, and use it in whatever manner you'd like, as long as you give me credit for the original, and do not claim it as your own. **************************************************************************

I'd like to thank:

Art Adamson for his matrix.e file.

Matthew Belmonte for fisher.c (an algorithm to perform an F-Test), which I've ported to Euphoria (see rgrseval.e).

Gabrial Boehme for print.e, which I've turned into sprint.e

Files:
 * matheval.e        Main include file
 * parseval.e        Core include file for parsing expressions
 * ppeval.e          Core include file for printing expressions
 * misceval.e        Core include file
 * symeval.e         Core include file for algebraic manipulation
 * sprint.e          Core include file for source code output
 * booleval.e        Boolean algebra
 * scripteval.e      Scripting with matheval
 * datetimeval.e     Dates and times
 * grapheval.e       Graph matheval expressions
 * mtrxeval.e        Matrix operations
 * matrix.e          included by mtrxeval.e
 * calceval.e        Calculus
 * stateqns.e        Some statistical formulae
 * rgrseval.e        Linear regression (uses stateqns.e)
 * solveval.e        Solving simple equations (not very well)
 * mathdemo.ex       Simple command line interactive demo
 * mathscript.ex     Runs matheval script files
 * normal.txt        Script file that calulates cumulative normal probabilities
 * normdemo.txt      Uses normal.mes to calculate some probabilities

Table of Contents
Topic	Description
Index	Alphabetical list of all items.
Algebra	Using variables and doing algebra
Arithmetic	Doing arithmetic
Boolean Algebra	Logical operators
Calculus	Topics related to calculus
Changes	The history of matheval
Expressions	Using matheval expressions
Extensions	Adding to matheval
Graphing	Graphing matheval expressions
Matrices	Working with matrices
Scripting	Loops, if-then, etc
Text Operations	Manipulating strings
Trigonometry	Trig functions

Algebra

Using variables and doing algebra

Variables in matheval are very powerful. They can hold any matheval expression as their value. This means that in addition to constants, they can hold functions and even other variables, which can in turn hold any matheval expression.

Variables may be assigned values using either SetVar() or through parsing and evaluating the ':=' operator. To clear the value of a variable, set it equal to itself ('x:=x'), or use ClearVar(). To determine the value of a variable, call Evaluate().

ex:
    sequence f, y

    -- f(x) = x + 1
    f = Evaluate( Parse( "f:=x+1") )

    -- output a pretty print of f
    printf(1, "F(X) = %s\n", { PPExp( f ) } )

    for x = 1 to 5 do
        SetVar( "X", x )

        -- y = f(x)
        y = Evaluate( f )
        printf(1, "F(%d) = %s\n", {x, PPExp(y)} )
    end for

const ClearVar( sequence var )

const Equals Topics related to graphs

func Evaluate_s( expression )

func GetVar( varname )

func GetVarList()

const Polynomial { POLYNOMIAL, "VARNAME", { a0, a1, a2, ... } }

func SetEqual( sequence a, sequence b)

proc SetVar( sequence var, object val ) Set a var's value.

func Simplify( sequence expr )

const Variable {VAR, "VARNAME", { coeff } }

Arithmetic

Doing arithmetic

const Addition { ADD, ARG1, ARG2 }

const Constant { CONSTANT, { val }, { } }

const Division { DIVIDE, ARG1, ARG2 }

const Exponentiation { EXPONENT, ARG1, ARG2 }

const Factorial { FACTORIAL, ARG1, { } }

const Multiplication { MULTIPLY, ARG1, ARG2 }

const ONE

const Subtraction { SUBTRACT, ARG1, ARG2 }

const TWO

const ZERO

Boolean Algebra

Logical operators

See booleval.e for source (you must explicitly include this file to use boolean algebra).

Boolean algebra functionality is included in the file booleval.e, which must be explicitly included to be used. It is not a part of the core matheval library.

const And { And, expr1, expr2 }

const Between { BETWEEN, expr1, {expr2,expr3} }

const EqualTo { EQUALTO, expr1, expr2 }

const Greater { GREATER, expr1, expr2 }

const GreaterOrEqual { GOE, expr1, expr2 }

const In { IN, expr1, expr2 }

const Less { GREATER, expr1, expr2 }

const LessOrEqual { GREATER, expr1, expr2 }

const Like { LIKE, expr1, expr2 }

const Not { NOT, constant, {} }

const NotEqual { NOTEQUAL, expr1, expr2 }

const Or { OR, expr1, expr2 }

Calculus

Topics related to calculus

See calceval.e for source.

const Derivative { DERIVATIVE, "VARNAME", ARG2 }

const Integrate Simple numerical integration

Changes

The history of matheval

Version 1.65 * Added datetimeval.e * Added UPPER and LOWER to texteval.e

Version 1.64 * Added parsing, pretty print for MATRIX, TRANSPOSE * Added SCRIPT operator to allow running files * Initialization in solveval was incorrect ( NOT pretty print initialization should have been for EQUALS ) * Added '<>' (not equals) to booleval.e

Version 1.63 * Fixed mtrxeval.e, rgrseval.e, stateqns.e to initialize properly

Version 1.62 * Fixed grapheval.e to initialize VAR and CONSTANT * IN properly evaluates if first argument is a variable

Version 1.61 * texteval.e allows string manipulation

Version 1.6 * scripteval.e allows Scripting ( IF, BLOCK, FOR, GOTO, LABEL, EXIT)

Version 1.52 * Added get_math_ref() * Can get matheval sequence in "source code format" using pp_source(). * Enhanced polynomial recognition. * Enhanced pretty print routines (multiply, add, polynomial) * Will multiply out polynomials and variables of where variables don't match

Version 1.51 * Fixed error in factorial calculations for any value over 11. * Minor bugfixes and improvements to parseval.e and ppeval.e

Version 1.5 * Booleval.e for evaluating boolean logic * Improved simplification routines in symeval.e

Version 1.4 * Improved simplifying routines in symeval.e. * Will expand expressions within an exponent fairly quickly now. * Tries to use polynomial multiplication.

Version 1.3 * A 'cumulative graphing feature, ie, growth/chaos functions.

Version 1.2 * Change modularization method. Added reg_math_func, resolve_math_func, add_to_func, eval_addons. Allows applications to add functions easier. * Able to create polynomials and do some simplification. Added distributive property. Still need to work on polynomials recognizing 3*x^2 as part of a polynomial.

Version 1.11 * Fixed bug in SetVar. Didn't set var equal to the evaluation of the parameter. Also allow x:=x to reset x. * Changed grapheval.e to use a default value for dx if an invalid value is supplied.

Version 1.1 * Changed variable handling. Variables are now allowed to have numbers and underscores in them, but must not start with a number. Also, variables can now begin with same characters as built in functions. * Included dummy functions for increased modular design.

Subtopics:

Parseval Changes

PPeval Changes

Symeval Changes

Expressions

Using matheval expressions

Matheval stores everything as a matheval sequence, which is nothing more than a three element sequence. The first element (you can use the global constant FUNC) identifies the type of matheval sequence. The second and third elements (which can be referred to as ARG1 and ARG2) are the arguments or data for the matheval sequence. They are always sequences (see matheval_seq)

Some matheval sequences use only ARG1, and others use both, depending on what they represent. A typical binary operator, like multiplication, uses both, and in fact, both ARG1 and ARG2 are matheval sequences themselves. Even normal numbers are represented as matheval sequences (see CONSTANT).

There are multiple ways to build matheval sequences. You can do it manually, within code, or you can use Parse() to turn a string into a matheval sequence. For example:

  x = Parse( "X + Y" )
  -- x = { ADD, { VAR, "X", {1}}, { VAR, "Y", {1} }

It is important to note that Parse() is case insensitive, except for text within quotes.

The various matheval types are described in this documentation as constants, which is slightly misleading. They are not true constants, but instead are values assigned at runtime during initialization (see matheval_init, add_math_init). They are always stored as local variables. In order to use them in your own code, you will need to declare them and make calls to resolve_math_ref to define them. This is done in order to make matheval more easily extendible and modular.

The documentation for these 'constants' will often say that they return a value. This is meant to convey that they are either a matheval function or a matheval operator that return some sort of value based on their arguments when they are evaluated (see Evaluate, Evaluate_s).

const Data { DATA, ARG1, ARG2 }

func Evaluate( expression )

const GetTol()

const Invalid { INVALID, "ERR MSG", { } }

proc matheval_init()

func Parse( sequence string ) Turns a string into a matheval sequence

proc parse_simplify( integer on )

const PPExp( expression ) Pretty Print

func pp_source( sequence expr )

proc SetTol( tolerance ) set the tolerance for pretty print

Extensions

Adding to matheval

Matheval is designed to allow user libraries to be added in a modular fashion. Several things need to be defined and initialized in order for additions to matheval to work properly. It must have a unique name and a function for evaluations. It may or may not have a parse or a pretty print routine (matrices have neither).

Its evaluation function is responsible for evaluating itself as well as its arguments (see GetArgs). It should handle all applicable cases for argument types, and if it cannot handle the types presented, should call eval_addons() to allow additional extensions. Likewise, to add support for a new matheval type to existing functions or operators, you should supply an evaluation function to be registered with add_to_func() so that matheval will know how to deal with your new type.

A matheval object is a sequence with three elements. The first is an integer, and identifies the object or function type. The second and third are the arguments or data for the object. If the object only needs one argument or data element, the last element should be an empty sequence. Constants are defined to reference the elements of a matheval object:

FUNC = 1
ARG1 = 2
ARG2 = 3

For instance, matheval does not have support for complex numbers, and even if you add a COMPLEX matheval object, ADD would not know how to add any expression containing complex numbers.

Evaluation functions should take two arguments (ARG1 and ARG2). If applicable, it should then call GetArgs, to make sure that the arguments have been fully evaluated. Then it should deal with the arguments as appropriate, or call eval_addons() if it cannot. It is not considered and error if no operations are possible. For instance, consider the case where the expression "x+y" is evaluated, but either (or both) x or y has not been assigned a value. See reg_math_func() for an example evaluation function.

The initialization procedure for an added file should do two things. It should register the additions and also resolve any references that it needs, since these are never declared as global. You will probably always need to resolve CONSTANT, and other simple functions like ADD or SUBTRACT. Take a look at any matheval file for an example initializtion function. Following is the initialization routine for booleval.e:

procedure boolean_init()
	-- need these references
    CONSTANT = resolve_math_ref( "CONSTANT" )
    INVALID = resolve_math_ref( "INVALID" )
    VAR = resolve_math_ref( "VAR" )
    POLYNOMIAL = resolve_math_ref( "POLYNOMIAL" )
    DATA = resolve_math_ref( "DATA" )
    LPAR = resolve_math_ref( "LPAR" )
    RPAR = resolve_math_ref( "RPAR" )

    -- register the functions being added
    NOT = reg_math_func( "NOT", routine_id("Not") )
    OR = reg_math_func( "OR", routine_id("Or") )
    AND = reg_math_func( "AND", routine_id("And") )
    LIKE = reg_math_func( "LIKE", routine_id("Like") )
    EQUALTO = reg_math_func( "EQUALTO", routine_id("EqualTo"))
    NOTEQUAL = reg_math_func( "NOTEQUAL", routine_id("NotEqual"))
    GREATER = reg_math_func( "GREATER", routine_id("Greater"))
    LESS = reg_math_func( "LESS", routine_id("Less"))
    GOE = reg_math_func( "GOE", routine_id("GreaterOrEqual"))
    LOE = reg_math_func( "LOE", routine_id("LessOrEqual"))
    BETWEEN = reg_math_func( "BETWEEN", routine_id("Between"))
    IN = reg_math_func( "IN", routine_id("In"))

    -- register the parsing routines
    reg_parse_func( "NOT", "NOT", routine_id("CNot"), 1, 5 )
    reg_parse_func( "OR", "OR", routine_id("COr"), 2, 6)
    reg_parse_func( "AND", "AND", routine_id("CAnd"), 2, 6)
    reg_parse_func( "LIKE", "LIKE", routine_id("CLike"), 2, 6)
    reg_parse_func( "EQUALTO", "=", routine_id("CEqualTo"), 2, 5)
    reg_parse_func( "GREATER", ">", routine_id("CGreater"), 2, 5)
    reg_parse_func( "LESS", "<", routine_id("CLess"), 2, 5)
    reg_parse_func( "GOE", ">=", routine_id("CGoe"), 2, 5)
    reg_parse_func( "LOE", "<=", routine_id("CLoe"), 2, 5)
    reg_parse_func( "BETWEEN", "BETWEEN", routine_id("CBetween"), 2, 5)
    reg_parse_func( "NOTEQUAL", "!=", routine_id("CNotEqual"), 2, 5)
    reg_parse_func( "IN", "IN", routine_id("CIn"), 2, 5)

	-- register the pretty print routines
    m:pretty_print( NOT, routine_id("PPNot"))
    m:pretty_print( OR, routine_id("PPOr"))
    m:pretty_print( AND, routine_id("PPAnd"))
    m:pretty_print( LIKE, routine_id("PPLike"))
    m:pretty_print( EQUALTO, routine_id("PPEqualTo"))
    m:pretty_print( GREATER, routine_id("PPGreater"))
    m:pretty_print( LESS, routine_id("PPLess"))
    m:pretty_print( GOE, routine_id("PPGoe"))
    m:pretty_print( LOE, routine_id("PPLoe"))
    m:pretty_print( BETWEEN, routine_id("PPBetween"))
    m:pretty_print( IN, routine_id("PPIn"))

end procedure
add_math_init( routine_id("boolean_init") )

proc add_math_init( integer id )

proc add_to_func( integer id, integer r_id )

func call_op( sequence obj )

func CheckCollapsed( sequence toks )

func CollapseToken( sequence expr, atom tok)

func eval_addons( integer from, sequence a, sequence b )

func GetArgs( sequence a, sequence b )

func get_math_ref( integer id )

func is_compound( sequence expr )

func make_first( sequence x, integer op )

func matheval_seq( object expr )

func math_func_count()

proc pretty_print( integer func, integer rid )

func reg_math_func( object ref, atom r_id )

proc reg_parse_func( object ref, object func, integer r_id, integer args, integer precedence )

func resolve_math_func( object ref )

func resolve_math_ref( object ref )

proc set_simplify( integer ref, integer simp )

func SyntaxError( sequence func )

Graphing

Graphing matheval expressions

const Graph { GRAPH, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }

const Range { RANGE, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }

proc ResetScreen()

proc SetOrigin( sequence xy )

proc SetScreen( sequence xy )

Matrices

Working with matrices

const Matrix { MATRIX, { type }, { matrix } }

const Transpose

Parseval Changes

Version 1.15 * Added parse_simplify() to control whether Parse() calls Simplify() * Will multipy RHS of SetEqual if not already done

Version 1.14 * Fixed bug parsing cos: unary, not binary * Recognizes variables typed in lowercase. * Improved parentheses error checking

Version 1.13 * Added Comma parsing: Turns a list into DATA.

Version 1.12 * Entire expression not converted to uppercase. Only uppercased when not inside quotes.

Version 1.11 * Added error checking. If invalid expression, entire expression is returned as invalid.

Supertopics:

Changes

PPeval Changes

Version 1.12 * Remove parenthesis from RHS of SetEqual * Added pp_source() * Multiply and Add are smarter about parenthesis, and look better * Fixed bug for polynomial where negative sign on first printed coefficient was dropped

Version 1.11 * Trig functions don't add an extra set of parenthesis. * Fixed tolerance bug for negative constants.

Version 1.1 * Minor changes to spacing for readability.

Supertopics:

Changes

Scripting

Loops, if-then, etc

By including scripteval.e, complex algorithms may be evaluated using matheval, including function and procedure calls by assigning a BLOCK to a variable.

const BLOCK { BLOCK, { [expr1], ... }, {} }

const COMMENT

const EXIT { EXIT, levels, {}}

const For { FOR, { variable, start, condition, increment operation }, expr }

const GOTO { GOTO, labelname, {} }

const IF { IF, condition, { true, false, [else] } }

const LABEL { LABEL, label, {}}

Symeval Changes

 Version 1.11
 * Improved polynomial recognition for cases like: (x-1)*3

 Version 1.1
 * Improved simplification to recognize cases like (x/y)*y = x

Supertopics:

Changes

Text Operations

Manipulating strings

By including texteval.e, you can access string manipulation functions.

const &

const LEFT( data, chars )

const LEN( data )

const LOWER

const MID( data, start, chars )

const RIGHT( data, chars )

const STR

const UPPER

const VAL

Trigonometry

Trig functions

const Cos { COS, ARG1, { } }

const Sin { SIN, ARG1, { } }

const Tan { TAN, ARG1, { } }

[const]
&

Category: Text Operations

Concatenates strings:

  "1234" & "5678" ->  "12345678"

See Also: LEFT, LEN, LOWER, MID, RIGHT, STR, UPPER, VAL

[const]
Addition

{ ADD, ARG1, ARG2 }

Returns: Sum of ARG1 and ARG2

Category: Arithmetic

[proc]
add_math_init ( integer id )

Category: Extensions

Adds the specified procedure to the list of initialization routines to be called from matheval_init().

[proc]
add_to_func ( integer id, integer r_id )

Category: Extensions

Used to dynamically add functionality to other matheval operations. For example, if you created a new data type (a complex number, for instance) you could specify how existing operations treat that type without modifying the code within the operation's evaluation functions.

[const]
And

{ And, expr1, expr2 }

Category: Boolean Algebra

If both expr1 and expr2 are nonzero constants, then ONE is returned. If at least one of expr1 or expr2 is ZERO, then returns ZERO.

See Also: Between, EqualTo, Greater, GreaterOrEqual, In, Less, LessOrEqual, Like, Not, NotEqual, Or

[const]
Between

{ BETWEEN, expr1, {expr2,expr3} }

Category: Boolean Algebra

Returns ONE if expr2 <= expr1 <= expr3, assuming that all are CONSTANT.

See Also: And, EqualTo, Greater, GreaterOrEqual, In, Less, LessOrEqual, Like, Not, NotEqual, Or

[const]
BLOCK

{ BLOCK, { [expr1], ... }, {} }

Category: Scripting

A set of statements to be evaluated sequentially. Blocks may contain other blocks. To parse a block, all expressions should be within parenthesis and separated by commas:

  "BLOCK( X:=1, FOR( I, 1, I<=5, I+1, X:=X*I))"

The value of a block of expressions will be the last expression evaluated.

See Also: COMMENT, EXIT, For, GOTO, IF, LABEL

[func]
call_op ( sequence obj )

Category: Extensions

Calls the evaluation routine for the matheval object obj, returning the result.

[func]
CheckCollapsed ( sequence toks )

Category: Extensions

Make sure that everything in the passed tokens is collapsed properly toks = { tok1, ... }

[const]
ClearVar ( sequence var )

Category: Algebra

If var = "VARNAME", then variable "VARNAME"'s value is cleared. If var = {}, then all variables are cleared.

[func]
CollapseToken ( sequence expr, atom tok)

Category: Extensions

Used to collapse tokens, and adds some error checking to make sure that there is a routine for the token. This should be used within parsing routines to ensure that tokens are fully collapsed (parsed) before they are made into an argument for another token.

[const]
COMMENT

Category: Scripting

Comments are removed during parsing, along with the next token. If the comment has any whitespace, it should be in quotes:

  -- "This is a comment"

See Also: BLOCK, EXIT, For, GOTO, IF, LABEL

[const]
Constant

{ CONSTANT, { val }, { } }

Category: Arithmetic

[const]
Cos

{ COS, ARG1, { } }

Returns: Cosine of ARG1

Category: Trigonometry

[const]
Data

{ DATA, ARG1, ARG2 }

Category: Expressions

Data is a way to pass data in an arbitrary format. This is used by Graph and Range to pass values, as well as by boolean evaluators to compare strings.

[const]
Derivative

{ DERIVATIVE, "VARNAME", ARG2 }

Returns: Derivative of ARG2 with respect to "VARNAME"

Category: Calculus

This only handles simple functions right now. Derivative may not be parsed.

[const]
Division

{ DIVIDE, ARG1, ARG2 }

Returns: Quotient of ARG1 divided by ARG2

Category: Arithmetic

[const]
Equals

Topics related to graphs

Category: Algebra

Used to solve equations. Still fairly primitive, and is prone to enter infinite loops. Use with caution. To Parse, use '=' (single equal sign).

[const]
EqualTo

{ EQUALTO, expr1, expr2 }

Category: Boolean Algebra

Similar to Like, but without wildcards. Returns ONE if expr1 is equal to expr2 by comparing ARG1 of each if either both are CONSTANT or one is a CONSTANT and the other is DATA.

See Also: And, Between, Greater, GreaterOrEqual, In, Less, LessOrEqual, Like, Not, NotEqual, Or

[func]
Evaluate ( expression )

Category: Expressions

Evaluates a matheval sequence. Performs as many operations as possible, returning the result.

[func]
Evaluate_s ( expression )

Category: Algebra

Calls Evaluate() and then Simplify().

[func]
eval_addons ( integer from, sequence a, sequence b )

Category: Extensions

Used to evaluate any additional operations that may have been set by add_to_func(). This should be called from within the evaluation routine of every matheval type.

[const]
EXIT

{ EXIT, levels, {}}

Category: Scripting

Exit from a block of expressions or a loop. EXIT allows multiple levels of escape from loops or blocks. The correct format is:

  "EXIT(levels)"

levels can be any valid matheval expression. If levels does not evaluate to a CONSTANT, or if it is less than or equal to zero, no exit will occur.

See Also: BLOCK, COMMENT, For, GOTO, IF, LABEL

[const]
Exponentiation

{ EXPONENT, ARG1, ARG2 }

Returns: ARG1 ^ ARG2

Category: Arithmetic

[const]
Factorial

{ FACTORIAL, ARG1, { } }

Returns: Factorial of ARG1

Category: Arithmetic

Parse uses standard x notation for the factorial of x. The maximum value of x is 17 due to the fact that Euphoria only provides 15 digits of accuracy.

[const]
Floor

{ FLOOR, ARG1, { } }

Returns: Greatest integer less than ARG1.

Category: Functions

Parse uses floor( ARG1 ) for the floor function.

[const]
For

{ FOR, { variable, start, condition, increment operation }, expr }

Category: Scripting

A for loop for matheval. It is similar in operation to a C-style for-loop. ARG1 is a 4 element sequence. expr will be evaluated as long as condition is true. The statement:

  "FOR(X, 1, X<=10, X+1,Y:=Y+1)"

...would parse to:

  { FOR,
      { "X", ONE, { LTOE, {VAR, "X", {1}}, {POLYNOMIAL, "X", {1,1}},
      { SETEQUALTO,
          {VAR, "Y", {1}},
          { POLYNOMIAL, "Y", {1,1}}}}

A single command or expression or a BLOCK of commands or expressions may be executed by FOR. The value of a FOR loop is the value of the last expression evaluated in the block of code, or the block of code itself, if it was never evaluated.

See Also: BLOCK, COMMENT, EXIT, GOTO, IF, LABEL

[func]
GetArgs ( sequence a, sequence b )

Category: Extensions

This is the main function for recursively dealing with arguments. Most ops pass their arguments to GetArgs(), which in turn evaluates the arguments as far as possible (ie, constants or undefined vars). Then it passes the values back to the original caller.

[const]
GetTol ()

Returns: Tolerance

Category: Expressions

The tolerance is primarily used for pretty print routines, to correctly return integer values.

[func]
GetVar ( varname )

Returns: Assigned value of variable

Category: Algebra

var should be the name of the variable. If the variable has not been defined, GetVar will return a matheval VAR sequence, with the specified name, and a coefficient of 1.

[func]
GetVarList ()

Category: Algebra

Returns an associative list where the first list is the name of all currently known variables, and the second list contains the corresponding values of all the variables.

[func]
get_math_ref ( integer id )

Category: Extensions

Returns the name of the matheval type, given its registered id.

[const]
GOTO

{ GOTO, labelname, {} }

Category: Scripting

Allows the evaluation of a block of expressions to jump to a label within the same block or within a parent block:

  BLOCK(
         X := 1
         LABEL("start"),
         X := X + 1,
         IF( X < 5, GOTO("start"), EXIT(1) )
        )

The labelname may be any expression, but note that labels are case sensitive. If an invalid label name is supplied, the result will be an INVALID value, and the block will exit. When the label is not in the current BLOCK, it will exit the current scope and look for the label there, until all blocks have been exited.

See Also: BLOCK, COMMENT, EXIT, For, IF, LABEL

[const]
Graph

{ GRAPH, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }

Returns: Data sequence of scaled coordinates

Category: Graphing

function: matheval sequence to be evaluated

Varname: independent variable

lbx: lower bound for independent variable

ubx: upper bound for independent variable

dx: incremental change in independent variable for evaluation

lby: lower bound for dependent variable

uby: upper bound for dependent variable Graph returns coordinates scaled per the values specified by SetScreen and by SetOrigin

See Also: Range, ResetScreen, SetOrigin, SetScreen

[const]
Greater

{ GREATER, expr1, expr2 }

Category: Boolean Algebra

Returns ONE if expr1 and expr2 are both CONSTANT and expr1[ARG1] > expr2[ARG2]. If one expression is CONSTANT and the other is DATA, returns ZERO.

See Also: And, Between, EqualTo, GreaterOrEqual, In, Less, LessOrEqual, Like, Not, NotEqual, Or

[const]
GreaterOrEqual

{ GOE, expr1, expr2 }

Category: Boolean Algebra

Returns ONE if expr1 and expr2 are both CONSTANT and expr1[ARG1] >= expr2[ARG2].

See Also: And, Between, EqualTo, Greater, In, Less, LessOrEqual, Like, Not, NotEqual, Or

[const]
IF

{ IF, condition, { true, false, [else] } }

Category: Scripting

Conditional calculation. If condition is ZERO, then false is calculated. If condition is a non-zero CONSTANT, then true is calculated. You may optionally specify else, which will be called if condition does not evaluate to a constant.

See Also: BLOCK, COMMENT, EXIT, For, GOTO, LABEL

[const]
In

{ IN, expr1, expr2 }

Category: Boolean Algebra

Both expr1 and expr2 must be DATA. expr2 should be a compound DATA object:

{ DATA, {expr1, expr2, ...}, {}}

Each expression will be evaluated, and if one is identical to expr1 then the return value will be ONE.

[const]
Integrate

Simple numerical integration

Returns: Riemann sum of funcion over specified range

Category: Calculus

Example: { INTEGRATE, { var, lower, upper, increment}, function }

var: variable over which to integrate

lower: lower bound

upper: upper bound

increment: width of rectangles to use in Riemann sums

function: matheval sequence to be evaluated

[const]
Invalid

{ INVALID, "ERR MSG", { } }

Category: Expressions

Invalid is used by Matheval to send back error messages to the user.

[func]
is_compound ( sequence expr )

Category: Extensions

Determines whether or not expr is a compound DATA sequence:

 { DATA, { {CONSTANT, {5}, {}}, ...}, {} }

If true, returns the number of matheval sequences contained within the DATA.

[const]
LABEL

{ LABEL, label, {}}

Category: Scripting

A target for GOTO from within a BLOCK. The proper syntax when parsing is:

   LABEL("THIS LABEL")

Note that labels are case sensitive, and must be strings (/DATA) only.

See Also: BLOCK, COMMENT, EXIT, For, GOTO, IF

[const]
LEFT ( data, chars )

Category: Text Operations

Returns the first chars elements of data

  LEFT("1234567", 4 )  -> "1234"

See Also: &, LEN, LOWER, MID, RIGHT, STR, UPPER, VAL

[const]
LEN ( data )

Category: Text Operations

Returns the length of data.

  LENFT("1234567")  -> 7

See Also: &, LEFT, LOWER, MID, RIGHT, STR, UPPER, VAL

[const]
Less

{ GREATER, expr1, expr2 }

Category: Boolean Algebra

Returns ONE if expr1 and expr2 are both CONSTANT and expr1[ARG1] < expr2[ARG2]. If one expression is CONSTANT and the other is DATA, returns ZERO.

See Also: And, Between, EqualTo, Greater, GreaterOrEqual, In, LessOrEqual, Like, Not, NotEqual, Or

[const]
LessOrEqual

{ GREATER, expr1, expr2 }

Category: Boolean Algebra

Returns ONE if expr1 and expr2 are both CONSTANT and expr1[ARG1] <= expr2[ARG2]. If one expression is CONSTANT and the other is DATA, returns ZERO.

See Also: And, Between, EqualTo, Greater, GreaterOrEqual, In, Less, Like, Not, NotEqual, Or

[const]
Like

{ LIKE, expr1, expr2 }

Category: Boolean Algebra

Compares objects. If the objects are identical, it will return ONE. Like's main purpose, however, is for comparing strings, including with wildcards (see Euphoria documentation on wildcard_match for details). A string is represented as a DATA object, with the string itself being the value of ARG1.

See Also: And, Between, EqualTo, Greater, GreaterOrEqual, In, Less, LessOrEqual, Not, NotEqual, Or

[const]
LOWER

Category: Text Operations

Converts to lower case.

See Also: &, LEFT, LEN, MID, RIGHT, STR, UPPER, VAL

[func]
make_first ( sequence x, integer op )

Category: Extensions

This function is useful from inside of evaluation routines, where x is the sequence {ARG1, ARG2}. If you know that one of the objects is of type op, and would like to have it be the first, make_first() will swap the order of x if required. This is convenient, because the order of arguments does not change the result of many operations (they are commutative).

[proc]
matheval_init ()

Category: Expressions

This routine must be called after matheval files are included. Multiple calls may be made, and each initialization routine will be called only once.

[func]
matheval_seq ( object expr )

Category: Extensions

Returns true (1) if expr is a sequence with length 3, and the first element is an integer, and the last two elements are both sequences.

[func]
math_func_count ()

Category: Extensions

Returns the number of matheval objects registered.

[const]
Matrix

{ MATRIX, { type }, { matrix } }

Category: Matrices

Type 0 is a column matrix, 1 is row matrix. All elements must be numbers (no variables, or any sort of matheval sequence). You can Add, Subtract, Multiply, Exponentiate, and Transpose a matrix. To find the inverse, Exponentiate using -1 as the exponent.

A matrix can be parsed:

    MATRIX( orientation, data )
       orientation = 0, 1 "R", "C"
       data = rows or column values inside of parenthesis
         The matrix: [1 2]
                     [3 4]
         could be parsed as either:
             MATRIX( "R", ( (1,2), (3,4) ) )
                 -- OR --
             MATRIX( "C", ( (1,3), (2,4) ) )

[const]
MID ( data, start, chars )

Category: Text Operations

Returns chars elements of data starting with element start.

  MID("1234567", 3, 2 )  -> "34"

See Also: &, LEFT, LEN, LOWER, RIGHT, STR, UPPER, VAL

[]
Miscellaneous Notes

Category: Miscellaneous Notes

[const]
Multiplication

{ MULTIPLY, ARG1, ARG2 }

Returns: Product of ARG1, ARG2 }

Category: Arithmetic

[const]
Not

{ NOT, constant, {} }

Category: Boolean Algebra

Logical not operator. Returns ONE if ARG1 is ZERO, or ZERO if ARG1 is a CONSTANT. Otherwise it evaluates ARG1 and returns {NOT, ARG1, {}}.

See Also: And, Between, EqualTo, Greater, GreaterOrEqual, In, Less, LessOrEqual, Like, NotEqual, Or

[const]
NotEqual

{ NOTEQUAL, expr1, expr2 }

Category: Boolean Algebra

Converse of EqualTo. Returns ZERO if expr1 is equal to expr2 by comparing ARG1 of each if either both are CONSTANT or one is a CONSTANT and the other is DATA.

This inequality may be expressed in two ways:

   expr1 != expr2
   expr1 <> expr2

See Also: And, Between, EqualTo, Greater, GreaterOrEqual, In, Less, LessOrEqual, Like, Not, Or

[const]
ONE

Category: Arithmetic

Shorthand for 1 as a matheval constant.

[const]
Or

{ OR, expr1, expr2 }

Category: Boolean Algebra

If both expr1 and expr2 are ZERO, then ZERO is returned. If at least one of expr1 or expr2 is a nonzero CONSTANT, then returns ONE.

[func]
Parse ( sequence string )

Turns a string into a matheval sequence

Returns: Parsed matheval sequence

Category: Expressions

String is a string such as "X+1", which Parse will return as a simplified matheval sequence. After Parse parses the string, is passes the result to Simplify.

[proc]
parse_simplify ( integer on )

Category: Expressions

Changes the behavior of Parse(). If on is zero, then parsed expressions are not simplified (see Simplify) before returning. Expressions are simplified by default.

[const]
Polynomial

{ POLYNOMIAL, "VARNAME", { a0, a1, a2, ... } }

Category: Algebra

ARG2 is a sequence of the coefficients: Example:

          { POLYNOMIAL, "X", {1,0,2,0,3} }
          is the same as
          3X^4 + 2X^2 + 1

[const]
PPExp ( expression )

Pretty Print

Returns: String representation of a matheval sequence

Category: Expressions

[func]
pp_source ( sequence expr )

Category: Expressions

Returns a string representing the matheval expression in source code form. The string will be broken into lines, with each line a separate sequence. Each line will be indented using tabs, so that m:ARG1 and ARG2 have one more tab than the m:FUNC for a matheval sequence:

  X + 2 =>
  { POLYNOMIAL,
      "X",
      {2,1}}

[proc]
pretty_print ( integer func, integer rid )

Category: Extensions

Registers a pretty print function so that the matheval type can be pretty printed. The function should return formatted text. It should call the pretty print routines for its argument[s] using call_func. The routine id of the function is available through the global sequence PPEXP, using the value of FUNC as index. Here is what the pretty print routine for ADD looks like:

ex:
	function PPAdd( sequence a, sequence b )
	    return "(" & call_func( PPEXP[a[FUNC]], {a[ARG1], a[ARG2]} ) & " + " &
	        call_func( PPEXP[b[FUNC]], {b[ARG1], b[ARG2]}) & ")"
	end function

NOTE: This procedure is located within matheval, and will conflict with the pretty_print() defined in the version of misc.e that comes with Euphoria 2.4 and later. It is advised to include matheval into a namespace if you call pretty_print (and will need to include misc.e into a namespace if you call misc:pretty_print().

[const]
Range

{ RANGE, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }

Returns: Data sequence of domain and range

Category: Graphing

function: matheval sequence to be evaluated

Varname: independent variable

lbx: lower bound for independent variable

ubx: upper bound for independent variable

dx: incremental change in independent variable for evaluation lby and uby are not used in Range. Range returns the actual values generated by evaluating the funcion.

See Also: Graph, ResetScreen, SetOrigin, SetScreen

[func]
reg_math_func ( object ref, atom r_id )

Category: Extensions

Should be called from within a file's initialization routine. It returns the id of the object. r_id is the routine id for the function to be called by evaluate. Following is the evaluation function for /FLOOR.

ex:
	function Floor( sequence a, sequence b )
	    a = call_op( a )
	
	    if a[FUNC] = CONSTANT then
	        return { CONSTANT, { floor(a[ARG1][1]) }, {} }
	    else
	        return eval_addons( FLOOR, a, b )
	    end if
	
	end function

[proc]
reg_parse_func ( object ref, object func, integer r_id, integer args, integer precedence )

Category: Extensions

Matheval needs to be told how to parse a new function or operator. This requires that matheval know the reference name (/resolve_math_ref), function or operator name, the routine id for the parse function, the number of arguments and the precedence. This is done by calling reg_parse_func(). The call for ADD looks like this:

reg_parse_func( "ADD", "+", routine_id("CAdd"), 2, 5 )

The parsing function's job is to 'collapse' the token and its arguments into one token, and is responsible for checking for errors, such as an incorrect number of arguments being supplied (e.g., for "1*2+" CAdd should return an error, since it would expect another token after it.

Here is what CAdd() looks like:

function CAdd( sequence expr, atom tok )
    sequence func
    func = expr[tok]
    if tok = 1 then
        return expr[2..length(expr)]
    elsif tok = length(expr) then
        return {{ INVALID, "+ Cannot find right arg", {}}}
    elsif expr[tok+1][m:FUNC] = SUBTRACT then

        return call_func(ColTok[SUBTRACT],
            { expr[1..tok-1] & expr[tok+1..length(expr)], tok})
    else
        if CheckCollapsed( {expr[tok-1], expr[tok+1]} ) then
            func = {func[m:FUNC], expr[tok-1], expr[tok+1] }
        else
            return SyntaxError("+")
        end if
    end if
    return expr[1..tok-2] & {func} & expr[tok+2..length(expr)]
end function

expr is the entire expression being parsed, and tok is the index to the token that CAdd() needs to parse. The routine first checks to make sure that there are tokens on either side of it. Since "+1" is really valid, it is not flagged as an error, but rather ignored. Errors should be flagged by returning the INVALID token, with m:ARG1 as a description of the error.

[proc]
ResetScreen ()

Category: Graphing

Resets graphing screen size to 0. Equivalent to SetScreen ( {0,0} )

See Also: Graph, Range, SetOrigin, SetScreen

[func]
resolve_math_func ( object ref )

Category: Extensions

Returns the routine id for the evaluation function of the matheval object ref.

ex:

	ADD_rid = resolve_math_func( "ADD" )

[func]
resolve_math_ref ( object ref )

Category: Extensions

Returns the id for the matheval object ref.

ex:

	ADD = resolve_math_ref( "ADD" )

[const]
RIGHT ( data, chars )

Category: Text Operations

Returns the last chars elements of data

  RIGHT("1234567", 4 )  -> "4567"

See Also: &, LEFT, LEN, LOWER, MID, STR, UPPER, VAL

[func]
SetEqual ( sequence a, sequence b)

Category: Algebra

{ SETEQUAL, ARG1, ARG2 } Set Variable in ARG1 equal to ARG2. Use ':=' when passed to Parse. To clear the value of a variable, use:

 "variable_name := variable_name"

[proc]
SetOrigin ( sequence xy )

Category: Graphing

Sets the origin value used when Graph scales coordinates. The values passed should be the coordinates of the upper left corner of your display area for the graph.

Example:

       SetOrigin( { 30, 30 } )

See Also: Graph, Range, ResetScreen, SetScreen

[proc]
SetScreen ( sequence xy )

Category: Graphing

xy is a sequence containing the size in pixels of the area to which the Graph will be displayed. Example:

      SetScreen( { 100, 100 } )

See Also: Graph, Range, ResetScreen, SetOrigin

[proc]
SetTol ( tolerance )

set the tolerance for pretty print

Category: Expressions

The tolerance is primarily used for pretty print routines, to correctly return integer values.

[proc]
SetVar ( sequence var, object val )

Set a var's value.

Category: Algebra

 var = "VARNAME"
 val = atom               : var is set to a constant
     = 'string'           : var set to parsed value of val
     = matheval sequence  : var set to sequence (NOTE: There is
                            no error checking done to make sure
                            that sequence is correct.)
     = "varname"          : var is reset (taken out of VarVals)

[proc]
set_simplify ( integer ref, integer simp )

Category: Extensions

This can be called to identify expression types that should not be simplified (i.e., scripting commands).

[func]
Simplify ( sequence expr )

Returns: Algebraically simplified matheval sequence.

Category: Algebra

Simplify attempts to put the expression (which is a matheval sequence) into an algebraically simplified form by multiplying out, grouping and adding like terms and putting variables into polynomials.

ex:
         (X  Y) * Y     ==> X
         X + 1 + 3 + X   ==> 2X + 4
         X*X^2         ==> X^3

[const]
Sin

{ SIN, ARG1, { } }

Returns: Sine of ARG1

Category: Trigonometry

[const]
STR

Category: Text Operations

Converts a CONSTANT to a DATA string:

 {CONSTANT, {1}, {}} ->  {DATA, "1", {}}

See Also: &, LEFT, LEN, LOWER, MID, RIGHT, UPPER, VAL

[const]
Subtraction

{ SUBTRACT, ARG1, ARG2 }

Returns: Difference of ARG1 and ARG2

Category: Arithmetic

[func]
SyntaxError ( sequence func )

Category: Extensions

A generic func to take care of situation where there is incorrect syntax for a token (ie, wrong args).

[const]
Tan

{ TAN, ARG1, { } }

Returns: Tangent of ARG1

Category: Trigonometry

[const]
Transpose

Category: Matrices

{ TRANSPOSE, MATRIX, {} } Transposes a matrix. To parse a Transpose operation:

    TRANSPOSE( matrix )

[const]
TWO

Category: Arithmetic

Shorthand for 2 as a matheval constant.

[const]
UPPER

Category: Text Operations

Converts to upper case.

See Also: &, LEFT, LEN, LOWER, MID, RIGHT, STR, VAL

[const]
VAL

Category: Text Operations

Converts a DATA string to a CONSTANT:

 {DATA, "1", {}} -> {CONSTANT, {1}, {}}

See Also: &, LEFT, LEN, LOWER, MID, RIGHT, STR, UPPER

[const]
Variable

{VAR, "VARNAME", { coeff } }

Returns: Assigned value of variable

Category: Algebra

Variables can hold any valid matheval value, including other variables, constants, or even complex expressions.

[const]
ZERO

Category: Arithmetic

Shorthand for 0 as a matheval constant.

Index

& [const]
Addition [const] { ADD, ARG1, ARG2 }
add_math_init [proc]
add_to_func [proc]
Algebra
And [const] { And, expr1, expr2 }
Arithmetic
Between [const] { BETWEEN, expr1, {expr2,expr3} }
BLOCK [const] { BLOCK, { [expr1], ... }, {} }
Boolean Algebra
Calculus
call_op [func]
Changes
CheckCollapsed [func]
ClearVar [const]
CollapseToken [func]
COMMENT [const]
Constant [const] { CONSTANT, { val }, { } }
Cos [const] { COS, ARG1, { } }
Data [const] { DATA, ARG1, ARG2 }
Derivative [const] { DERIVATIVE, "VARNAME", ARG2 }
Division [const] { DIVIDE, ARG1, ARG2 }
Equals [const] Topics related to graphs
EqualTo [const] { EQUALTO, expr1, expr2 }
Evaluate [func]
Evaluate_s [func]
eval_addons [func]
EXIT [const] { EXIT, levels, {}}
Exponentiation [const] { EXPONENT, ARG1, ARG2 }
Expressions
Extensions
Factorial [const] { FACTORIAL, ARG1, { } }
Floor [const] { FLOOR, ARG1, { } }
For [const] { FOR, { variable, start, condition, increment operation }, expr }
GetArgs [func]
GetTol [const]
GetVar [func]
GetVarList [func]
get_math_ref [func]
GOTO [const] { GOTO, labelname, {} }
Graph [const] { GRAPH, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }
Graphing
Greater [const] { GREATER, expr1, expr2 }
GreaterOrEqual [const] { GOE, expr1, expr2 }
IF [const] { IF, condition, { true, false, [else] } }
In [const] { IN, expr1, expr2 }
Integrate [const] Simple numerical integration
Invalid [const] { INVALID, "ERR MSG", { } }
is_compound [func]
LABEL [const] { LABEL, label, {}}
LEFT [const]
LEN [const]
Less [const] { GREATER, expr1, expr2 }
LessOrEqual [const] { GREATER, expr1, expr2 }
Like [const] { LIKE, expr1, expr2 }
LOWER [const]
make_first [func]
matheval_init [proc]
matheval_seq [func]
math_func_count [func]
Matrices
Matrix [const] { MATRIX, { type }, { matrix } }
MID [const]
Miscellaneous Notes []
Multiplication [const] { MULTIPLY, ARG1, ARG2 }
Not [const] { NOT, constant, {} }
NotEqual [const] { NOTEQUAL, expr1, expr2 }
ONE [const]
Or [const] { OR, expr1, expr2 }
Parse [func] Turns a string into a matheval sequence
Parseval Changes
parse_simplify [proc]
Polynomial [const] { POLYNOMIAL, "VARNAME", { a0, a1, a2, ... } }
PPeval Changes
PPExp [const] Pretty Print
pp_source [func]
pretty_print [proc]
Range [const] { RANGE, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }
reg_math_func [func]
reg_parse_func [proc]
ResetScreen [proc]
resolve_math_func [func]
resolve_math_ref [func]
RIGHT [const]
Scripting
SetEqual [func]
SetOrigin [proc]
SetScreen [proc]
SetTol [proc] set the tolerance for pretty print
SetVar [proc] Set a var's value.
set_simplify [proc]
Simplify [func]
Sin [const] { SIN, ARG1, { } }
STR [const]
Subtraction [const] { SUBTRACT, ARG1, ARG2 }
Symeval Changes
SyntaxError [func]
Tan [const] { TAN, ARG1, { } }
Text Operations
Transpose [const]
Trigonometry
TWO [const]
UPPER [const]
VAL [const]
Variable [const] {VAR, "VARNAME", { coeff } }
ZERO [const]

Introduction

Matheval v1.65

What is matheval?

Topic

Description

Using variables and doing algebra

Doing arithmetic

Logical operators

Topics related to calculus

The history of matheval

Using matheval expressions

Adding to matheval

Graphing matheval expressions

Working with matrices

Loops, if-then, etc

Manipulating strings

Trig functions

{ ADD, ARG1, ARG2 }

Returns: Sum of ARG1 and ARG2

[proc]add_math_init ( integer id )

[proc]add_to_func ( integer id, integer r_id )

{ And, expr1, expr2 }

{ BETWEEN, expr1, {expr2,expr3} }

{ BLOCK, { [expr1], ... }, {} }

[func]call_op ( sequence obj )

[func]CheckCollapsed ( sequence toks )

[const]ClearVar ( sequence var )

[func]CollapseToken ( sequence expr, atom tok)

{ CONSTANT, { val }, { } }

{ COS, ARG1, { } }

Returns: Cosine of ARG1

{ DATA, ARG1, ARG2 }

{ DERIVATIVE, "VARNAME", ARG2 }

Returns: Derivative of ARG2 with respect to "VARNAME"

{ DIVIDE, ARG1, ARG2 }

Returns: Quotient of ARG1 divided by ARG2

Topics related to graphs

{ EQUALTO, expr1, expr2 }

[func]Evaluate ( expression )

[func]Evaluate_s ( expression )

[func]eval_addons ( integer from, sequence a, sequence b )

{ EXIT, levels, {}}

{ EXPONENT, ARG1, ARG2 }

Returns: ARG1 ^ ARG2

{ FACTORIAL, ARG1, { } }

Returns: Factorial of ARG1

{ FLOOR, ARG1, { } }

Returns: Greatest integer less than ARG1.

{ FOR, { variable, start, condition, increment operation }, expr }

[func]GetArgs ( sequence a, sequence b )

[const]GetTol ()

Returns: Tolerance

[func]GetVar ( varname )

Returns: Assigned value of variable

[func]GetVarList ()

[func]get_math_ref ( integer id )

{ GOTO, labelname, {} }

{ GRAPH, { function, "Varname"}, {lbx, ubx, dx, lby, uby} }

Returns: Data sequence of scaled coordinates

[proc]
add_math_init ( integer id )

[proc]
add_to_func ( integer id, integer r_id )

[func]
call_op ( sequence obj )

[func]
CheckCollapsed ( sequence toks )

[const]
ClearVar ( sequence var )

[func]
CollapseToken ( sequence expr, atom tok)

[func]
Evaluate ( expression )

[func]
Evaluate_s ( expression )

[func]
eval_addons ( integer from, sequence a, sequence b )

[func]
GetArgs ( sequence a, sequence b )

[const]
GetTol ()

[func]
GetVar ( varname )

[func]
GetVarList ()

[func]
get_math_ref ( integer id )