JCalc

Warning

This repo is under active development yet. Changes can occur without warning, so use it at your own risk

Table of Contents

• Description of the project
• Getting the library
  • Building the library locally
  • Getting the library from JitPack
• Usage
  • Basic usage
  • Exceptions handling
• Related project (W.I.P.)
• About the docs
• Contribution

Description of the project

This repo holds the code of a Java library named JCalc that is especially made for those who, for any reason, want to allow users to input basic Math expressions in Java apps and quickly solve them during runtime (like, for example, when building a basic calculator). In order to make that possible, this library makes use of a custom implementation of the Shunting Yard algorithm that allows it to quickly parse and solve Math expressions written in the notation commonly used to write Math expressions; also known as infix notation.

JCalc comes with support for numbers written using a variant of the Scientific notation named E notation and, when writing the Math expressions, you can make use of parentheses ("(" and ")"), the plus symbol ("+"), the subtraction symbol ("-"), the multiplication symbol ("*" or "×"), the division symbol ("/" or "÷"), the exponentiation symbol ("^") and the factorial symbol ("!").

Warning

Any other operator or value not previously mentioned is currently not supported and using any of them will cause an exception.

All of the above means that you can use this library to solve statements like, for example:

• ((25*3-9)/(4+2)+5^3)-(48/8)*(7+2)+14 (which is equals to 96)
• 2 * 3 + 5 * 2^3 (which is equals to 46)
• 2 * -(3 + 4! / 2) + 5^2 (which is equals to -5)
• 3 + 4 * 2 / (1 - 5)^2^3 (which is equals to 3.000122070313)
• 1000 / (2^5) + (3!)^4 - 500 * (2 + 3) (which is equals to -1172.75)
• (8^2 + 15 * 4 - 7) / (3 + 5)*(12 - 9) + 6^2 - (18 /3) + 11 (which is equals to 84.875)
• (2^10)! / (2^(5!)) (which is equals to 4.076447993302E2603)
• ((100 + 200) * (300 - 150)) / (2^(3!)) + (7!)^25 (which is equals to 3.637168415833E92)
• (-2^3) * (-(3! + 4) / 2) + 5 (which is equals to 45)
• 2 + -3! * (-4^2) / (5 - 3) (which is equals to 50)

All the results previously shown were obtained with JCalc and checked using an online calculator app provided by Desmos in this website.

Getting the library

Building the library locally

To build the library locally, the first thing you must do is to make sure that you have a valid installation of the Java Development Kit (JDK). That can be easily checked by executing the following command in a terminal:

java --version

Tip

The minimum Java version required to build this library is Java 8.

If the execution of that command generates any output instead of an error message, then your installation of the JDK should be correct; and after effectively checking the JDK installation, you must create a local copy of this repo in your device. In order to do that, launch a terminal and execute the following command:

git clone https://github.com/jr20xx/JCalc

Once the execution of that command is finished, a new directory containing a copy of the files of this project will be created. You can open that folder with a Java IDE with Gradle support like IntelliJ IDEA, Android Studio or VSCode (with the Extension Pack for Java installed) and then build the library making use of their integrated tools. If you need help doing that, you can check this website to get references of how to do that in your preferred IDE.

If you decide to build the library without using any IDE, then open the newly created directory containing the files from this repo and start a terminal session from there. Once you've opened a terminal, run any of the following commands:

From Linux terminal:

./gradlew build

From Windows command line:

gradlew.bat build

Once the execution of that command is done, open the jcalc directory, then open the builds directory and, once you are watching its content, you'll see a folder named libs. In that last folder you'll find compiled files of the library, the Javadocs and the source code compressed as single JAR files that you can use as you wish.

Getting the library from JitPack

To ease the process of getting a compiled version of the library that you can use directly in your projects, you can use JitPack. In order to do that, follow the official guide provided here by JitPack.

Usage

Basic usage

To make use of this library, you simply have to call the method JCalc.solveMathExpression(...) providing it with a String containing the Math expression that you want to get solved and a boolean value used to specify when to automatically attempt to balance the parentheses in the given Math expression. When called, that method will return another String with the result of solving the given Math expression; but if the given expression is empty or contains only whitespaces, null will be returned instead of any result. In addition to all that, if the Math expression contains any whitespace, they'll be automatically removed.

Here's a clear code example for you to get an idea of how to work with the library and to allow you to know which is the method that must be called to get the work done:

String expression = "3 + 4 * 2 / (1 - 5)^2^3";
String result = JCalc.solveMathExpression(expression, true);
System.out.print(result); // Prints "3.000122070313"

Exceptions handling

This library contains a small set of custom exceptions that should be controlled to guarantee that the execution of the program doesn't get interrupted or glitched. Here's a Java snippet showing all of them with added comments explaining when they are expected to happen:

try {
    String expression = "2 * 3 + 5 * 2^3)";
    String result = JCalc.solveMathExpression(expression, true);
}
catch (UnbalancedParenthesesException exception) {
    // This exception occurs when the parentheses were not placed correctly and `false` is provided as second parameter
}
catch (NotNumericResultException exception) {
    // This exception occurs when a not numeric (NaN) value is obtained
}
catch (InfiniteResultException exception) {
    // This exception occurs when an Infinite result is obtained
}
catch (SyntaxErrorException exception) {
    // This exception occurs when an error is detected in the writing of the Math expression
}
catch (NumericalDomainErrorException exception) {
    // This exception occurs when trying to obtain the factorial of a number when it's negative or not an integer
}
catch (Exception exception) {
    // This is recommended in case that an unexpected exception arises
}

Related project (W.I.P.)

• Android Calculator

About the docs

The code included in this library includes Javadocs comments nearly everywhere and the rest of the code will be documented in the same way soon. Thanks to JitPack, you can read the online version of the Javadocs by visiting this website.

Contribution

We value a lot any kind of contribution and we encourage you to submit pull requests and to provide tutorials or other relevant content that might help to improve this library or extend its functionalities.

You can also contribute to this repo by adding a star to it and/or sharing the link if you find it helpful in some way. Any form of help will be highly appreciated.