This is a kotlin multiplatform runtime infix expressions evaluator.

The library supports the following operators and special symbols:

• +, -, *, / - mathematical operators
• % - modulo. Returns the remainder of a division, after one number is divided by another
• ^ - exponentiation. a^b means a raised to the power of b
• &&, ||, ! - logical 'and', 'or', 'not' operators
• ==, != - equality operators
• <, >, <=, >= - comparison operators
• a ? b : c - ternary operator

The library supports the following constants:

• pi - PI
• e - e
• any custom constants.

The library supports the following functions:

• abs(x) - absolute value
• acos(x) - arccosine
• asin(x) - arcsine
• atan(x) - arctangent
• avg(a1, a2, a3, ..., an) - average of N values
• ceil(x) - ceiling
• cos(x) - cosine
• cosh(x) - hyperbolic cosine
• floor(x) - floor
• ln(x) - natural logarithm
• log(x, base) - logarithm
• max(a1, a2, a3, ..., an) - maximum of N values
• min(a1, a2, a3, ..., an) - minimum of N values
• round(x) - rounding to the nearest integer
• sin(x) - sine
• sinh(x) - hyperbolic sine
• sum(a1, a2, a3, ..., an) - summation of N values
• tan(x) - tangent
• tanh(x) - hyperbolic tangent
• any custom function with any number of arguments

Any symbols other than constants and function calls are resolved as variables during evaluation.

The library is distributed via maven central repositories.

Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.murzagalin:multiplatform-expressions-evaluator:x.y.z")
}

Groovy

repositories {
    mavenCentral()
}

dependencies {
    implementation "io.github.murzagalin:multiplatform-expressions-evaluator:x.y.z"
}

import com.github.murzagalin.evaluator.Evaluator

val evaluator = Evaluator()

//numeric values
evaluator.evaluateDouble("23 + 0.123 * (124 / -60.124)")

//boolean values
evaluator.evaluateBoolean(
    "x > 1 && var",
    mapOf("x" to 3, "var" to true)
)

//variables
evaluator.evaluateDouble(
    "1 + x + y",
    mapOf("x" to 3, "y" to 4)
)

//functions
evaluator.evaluateDouble(
    "sin(x)^2+cos(x)^2",
    mapOf("x" to 2.0)
)

//constants
evaluator.evaluateDouble("cos(pi)")
evaluator.evaluateDouble("ln(e^3)")

The library supports custom functions with any number of arguments. Supported argument and return types are Double and Boolean

For the example I will explain how to create a function that represents the general form of normal distribution probability density function:

The function will have the following syntax: normal_dist(x, m, sigma). The parameter m is the mean of the distribution, while the parameter sigma is its standard deviation.

We define a function which is named "normal_dist" and has 3 arguments:

import com.github.murzagalin.evaluator.Function

object NormalDist : Function("normal_dist", 3) {
    override fun invoke(vararg args: Any): Any {
        val x = args.getAsDouble(0) { "$name argument must be a number" }
        val m = args.getAsDouble(1) { "$name mean must be a number" }
        val sigma = args.getAsDouble(2) { "$name sigma must be a number" }

        return 1.0 / sigma / sqrt(2 * PI) * exp(-1.0 / 2.0 * ((x - m) / sigma).pow(2))
    }
}

Note: the library checks if the number of arguments in an expression is equal to 3, otherwise it throws an exception. But you have to check the types of the arguments by yourself. Functions getAsDouble(index, lazyMessage) and getAsBoolean(index, lazyMessage) return an element at position index, and throw IllegalArgumentException with the message returned from lazyMessage if it has a wrong type

Then we add this function to the evaluator:

import com.github.murzagalin.evaluator.DefaultFunctions
import com.github.murzagalin.evaluator.Evaluator

fun main() {
    val evaluator = Evaluator(functions = DefaultFunctions.ALL + NormalDist)
    print(evaluator.evaluateDouble("normal_dist(12, 9, 3)"))
}

The process of creating functions with variable number of arguments is pretty much the same. The difference is how we define the function.

As an example I will create a function mult(a1, a2, ..., an) which is defined as a1 * a2 * ... * an:

object Mult: Function("mult", 2..Int.MAX_VALUE) {
    override fun invoke(vararg args: Any): Any {
        require(args.all { it is Double }) { "$name function requires all arguments to be numbers" }

        return args.fold(1.0) { acc, x -> acc * (x as Double) }
    }
}

Note: we define minimum and maximum number of arguments as a range. It is also possible to define them separately: Function("mult", 2, Int.MAX_VALUE)

Then we add this function to the evaluator:

import com.github.murzagalin.evaluator.DefaultFunctions
import com.github.murzagalin.evaluator.Evaluator

fun main() {
    val evaluator = Evaluator(functions = DefaultFunctions.ALL + Mult)
    print(evaluator.evaluateDouble("mult(2, 3, 4)"))
}

The library supports custom constants. For the example I will show you how to add a golden ratio constant. We will define the constant named phi with the value 1.6180339887:

import com.github.murzagalin.evaluator.Constant
import com.github.murzagalin.evaluator.DefaultConstants
import com.github.murzagalin.evaluator.Evaluator

fun main() {
    val PHI = Constant("phi", 1.6180339887)
    val evaluator = Evaluator(constants = DefaultConstants.ALL + PHI)
    print(evaluator.evaluateDouble("x * phi", mapOf("x" to 2)))
}

By default, the library does the following steps to evaluate an expression:

1. Tokenizing - splitting the expression into a list of units (operations, numbers, constants, function calls, etc.)
2. Converting the expression from infix notation to abstract syntax tree.
3. Evaluating the abstract syntax tree.

In case you have an expression with variables, it might make sense to preprocess the expression (do steps 1 and 2 in advance) to improve the performance:

import com.github.murzagalin.evaluator.Evaluator

fun main() {
    val evaluator = Evaluator()
    
    //step 1 and 2
    val preprocessedExpression = evaluator.preprocessExpression("1 + x + y^2")
    
    //step 3
    val result = evaluator.evaluateDouble(preprocessedExpression, mapOf("x" to 2, "y" to 4))
}

TBD

TBD

TBD

This library is available for free under Apache 2.0 license.

Copyright (c) 2021 Azamat Murzagalin.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.