A Kotlin mini library for math expression string evaluation
A Kotlin Multiplatform mini library for string evaluation
(You may need to watch out using it: having to evaluate a string into a number is more often than not a code smell)
You can import Keval directly with the jar files, or using your favorite dependency manager with the Maven Central repository:
Maven
<dependencies>
<dependency>
<groupId>com.notkamui.libs</groupId>
<artifactId>keval</artifactId>
<version>1.0.1</version>
</dependency>
</dependencies>
Gradle (here with KotlinDSL)
repositories {
mavenCentral()
}
dependencies {
implementation("com.notkamui.libs:keval:1.0.1")
}
(In case you're using it with another language than Kotlin -- i.e. Java --, make sure you include kotlin stdlib too)
Keval can evaluate a mathematical expression as a String
into a Double
value. It is customizable in the sense that
one can add new binary and unary operators, functions and constants.
The base settings of Keval already include sensible defaults for the most common mathematical operations.
Keval has support for all classic binary operators:
-
+
*
/
^
%
Keval has support for all classic unary operators:
-
(prefix)+
(prefix) (basically does nothing)!
(postfix)Keval has support for functions of variable arity:
neg(expr)
(where 'expr' is an expression)abs(expr)
(where 'expr' is an expression)sqrt(expr)
(where 'expr' is an expression)cbrt(expr)
(where 'expr' is an expression)exp(expr)
(where 'expr' is an expression)ln(expr)
(where 'expr' is an expression)log10(expr)
(where 'expr' is an expression)log2(expr)
(where 'expr' is an expression)sin(expr)
(where 'expr' is an expression)cos(expr)
(where 'expr' is an expression)tan(expr)
(where 'expr' is an expression)asin(expr)
(where 'expr' is an expression)acos(expr)
(where 'expr' is an expression)atan(expr)
(where 'expr' is an expression)ceil(expr)
(where 'expr' is an expression)floor(expr)
(where 'expr' is an expression)round(expr)
(where 'expr' is an expression)Keval has support for constants, it has two built-in constant:
PI
e
(Euler's number)You can optionally add as many operators, functions or constants to Keval, as long as you define every field properly, with a DSL (Domain Specific Language):
Char
that is NOT a digit, nor a letter, nor an underscore)Int
)Boolean
true if left associative, false otherwise)(Double, Double) -> Double
)Char
that is NOT a digit, nor a letter, nor an underscore)Boolean
)(Double) -> Double
)String
identifier, that doesn't start with a digit, and only contains letters, digits or
underscores)Int
)(DoubleArray) -> Double
)String
identifier, that doesn't start with a digit, and only contains letters, digits or
underscores)Double
)Keval will use the built-in operators, function and constants if you choose not to define any new resource ; but if you choose to do so, you need to include them manually. You may also choose to use Keval as an extension function.
Please note that adding a new resource with a name that already exists will overwrite the previous one, except in the case of operators, where one symbol can represent both a binary and a unary operator. For example, it is possible to define a binary operator
-
and a unary operator-
at the same time.
You can use it in several ways:
Keval.eval("(3+4)(2/8 * 5) % PI") // uses default resources
"(3+4)(2/8 * 5) % PI".keval() // extension ; uses default resources
Keval.create { // builder instance
includeDefault() // this function includes the built-in resources
binaryOperator { // this function adds a binary operator ; you can call it several times
symbol = ';'
precedence = 3
isLeftAssociative = true
implementation = { a, b -> a.pow(2) + b.pow(2) }
}
unaryOperator { // this function adds a unary operator ; you can call it several times
symbol = '#'
isPrefix = false
implementation = { arg -> (1..arg.toInt()).fold(0.0) { acc, i -> acc + i } }
}
function { // this function adds a function ; you can call it several times
name = "max"
arity = 2
implementation = { args -> max(args[0], args[1]) }
}
constant { // this function adds a constant ; you can call it several times
name = "PHI"
value = 1.618
}
}.eval("2*max(2, 3) ; 4# + PHI^2")
"2*max(2, 3) ; 4# + PHI^2".keval { // builder instance + extension
includeDefault()
binaryOperator {
symbol = ';'
precedence = 3
isLeftAssociative = true
implementation = { a, b -> a.pow(2) + b.pow(2) }
}
unaryOperator {
symbol = '#'
isPrefix = false
implementation = { arg -> (1..arg.toInt()).fold(0.0) { acc, i -> acc + i } }
}
function {
name = "max"
arity = 2
implementation = { args -> max(args[0], args[1]) }
}
constant {
name = "PHI"
value = 1.618
}
}
The advantage of using Keval.create
is that you may keep an instance of it in a variable so that you can call as
many eval
as you need.
In concordance with creating a Keval instance, you can also add resources like this:
val kvl = Keval().create {}
.withDefault() // includes default resources // it is unnecessary here since Keval() with no DSL already does it
.withBinaryOperator( // includes a new binary operator
';', // symbol
3, // precedence
true // isLeftAssociative
) { a, b -> a.pow(2) + b.pow(2) } // implementation
.withUnaryOperator( // includes a new unary operator
'#', // symbol
false, // isPrefix
) { arg -> (1..arg.toInt()).fold(0.0) { acc, i -> acc + i } } // implementation
.withFunction( // includes a new function
"max", // name
2 // arity
) { max(it[0], it[1]) } // implementation
.withConstant( // includes a new constant
"PHI", // name
1.618 // value
)
kvl.eval("2*max(2, 3) ; 4# + PHI^2")
This can be combined with creating an instance with a DSL (i.e. Keval.create
).
This is an especially useful syntax for Java users, since DSLs generally don't translate well over it.
Creating a resource with a name that already exists will overwrite the previous one.
Keval assumes products/multiplications, and as such, the * symbol/name cannot be overwritten, and is the only operator to always be present in the resource set of a Keval instance:
"(2+3)(6+4)".keval() == "(2+3)*(6+4)".keval()
In addition, the symbols (
,)
,,
are reserved and trying to create operator using one of those symbols will result with an exception.
In case of an error, Keval will throw one of several KevalException
s:
KevalZeroDivisionException
in the case a zero division occursKevalInvalidArgumentException
in the case a operator or function is called with an invalid argument (i.e. a negative number
for a factorial)KevalInvalidExpressionException
if the expression is invalid, with the following properties:
expression
contains the fully sanitized expressionposition
is an estimate of the position of the errorKevalInvalidSymbolException
if the expression contains an invalid operator, with the following properties:
invalidSymbol
contains the actual invalid operatorexpression
contains the fully sanitized expressionposition
is an estimate of the position of the errorKevalDSLException
if, in the DSL, one of the field is either not set, or doesn't follow its restrictions (defined
above)KevalZeroDivisionException
and KevalInvalidArgumentException
are instantiable so that you can throw them when
implementing a custom operator/function.
DoubleArray
instead of a single Double
)