tiny_expr 0.3.1

SDKdartflutter
Platformandroidioswindowslinuxmacosweb

A Dart library for evaluating mathematical expressions with support for variables and functions.

TinyExpr is a lightweight expression evaluator for Dart, designed to evaluate mathematical expressions from strings. This makes it an ideal choice for applications requiring dynamic calculations.

This project draws inspiration from the TinyExpr library written in C. The original library can be found here. We extend our gratitude to the original author for their outstanding work.

Features

  • Evaluate mathematical expressions from strings.
  • Support for basic arithmetic operations: addition, subtraction, multiplication, and division.
  • Support for parentheses to define operation precedence.
  • Support for exponentiation.
  • Support for unary negation.
  • Support for constants (e.g., pi, e).
  • Support for trigonometric functions (e.g., sin, cos, tan, cosec, sec, cot).
  • Support for hyperbolic functions (e.g., sinh, cosh, tanh).
  • Support for logarithmic functions (e.g., log, ln).
  • Support for square root and absolute value.
  • Support for exponential function.
  • Support for rounding functions (e.g., ceil, floor).
  • Support for factorial, combinations (nCr), and permutations (nPr).
  • Lightweight and easy to integrate.
  • Support for extension method on String to directly use .evaluate() method.

Getting started

To start using TinyExpr, add it as a dependency in your pubspec.yaml file:

dependencies:
  tiny_expr: ^0.3.1

Then, run flutter pub get to install the package.

Usage

Simple Implementation

Here is a simple example of how to use TinyExpr to evaluate an expression:

import 'package:tiny_expr/tiny_expr.dart';

void main() {
  final expression = '3 + 5 * (2 - 4)';
  final result = TinyExpr(expression).evaluate();
  print('Result: $result'); // Output: Result: -7
}

Using Variables

Here is an example of how to use TinyExpr with variables:

import 'package:tiny_expr/tiny_expr.dart';

void main() {
  final expression = 'x + y * z';
  final te = TinyExpr(expression);
  te.addVariables({'x': 3.0, 'y': 2.0, 'z': 5.0});
  final result = te.evaluate();
  print('Result: $result'); // Output: Result: 13.0

  // Update variable values
  te.updateVariables({'x': 10.0});
  final updatedResult = te.evaluate();
  print('Updated Result: $updatedResult'); // Output: Updated Result: 20.0
}

Using Extension Method

TinyExpr now supports an extension method on String to directly evaluate expressions:

import 'package:tiny_expr/tiny_expr.dart';

void main() {
  final expression = '3 + 5 * (2 - 4)';
  final result = expression.evaluate();
  final expressionWithVariables = 'x + y';
  final resultWithVariables =
      expressionWithVariables.evaluate(variables: {'x': 2, 'y': 15});
  print('Result: $result'); // Output: Result: -7
  print('Result: $resultWithVariables'); // Output: Result: 17
}

For more examples, check the /example folder.

Available Operations

Operation TypeOperators/FunctionsUsage Example
Basic Arithmetic+, -, *, /, %2 + 3, 10 - 4, 6 * 7, 20 / 5, 8 % 3
Exponentiation^2^3
Parentheses()(2 + 3) * 4
Unary Negation--5, -(2 + 3)
Constantspi, epi, e
Trigonometric Functionssin, cos, tan, cosec, sec, cot, atan2sin(pi / 2), cos(pi), tan(pi / 4), cosec(pi / 2), sec(0), cot(pi / 4), atan2(1, 1)
Hyperbolic Functionssinh, cosh, tanhsinh(1), cosh(1), tanh(1)
Logarithmic Functionslog, lnlog(100), ln(e)
Square Rootsqrtsqrt(16)
Absolute Valueabsabs(-5)
Exponential Functionexpexp(1)
Rounding Functionsceil, floorceil(2.1), floor(2.9)
Factorialfac, !fac(5), 5!
Combinationsncrncr(5, 3)
Permutationsnprnpr(5, 2)

Test Coverage

The TinyExpr package includes comprehensive tests to ensure the correctness of the expression evaluation. The tests cover:

Test CategoryDescriptionStatus
Basic ArithmeticTests for addition, subtraction, multiplication, division, and modulo operations.✅
ExponentiationTests for power operations.✅
Parentheses and PrecedenceTests for parentheses and operator precedence.✅
Unary NegationTests for unary negation.✅
ConstantsTests for mathematical constants like pi and e.✅
Trigonometric FunctionsTests for trigonometric functions like sin, cos, tan, etc.✅
Hyperbolic FunctionsTests for hyperbolic functions like sinh, cosh, tanh.✅
Logarithmic FunctionsTests for logarithmic functions like log and ln.✅
Square Root and Absolute ValueTests for square root and absolute value functions.✅
Exponential FunctionTests for the exponential function.✅
Rounding FunctionsTests for rounding functions like ceil and floor.✅
FactorialTests for the factorial function.✅
Combinations and PermutationsTests for combinations (nCr) and permutations (nPr).✅
Variable HandlingTests for handling variables in expressions.✅
Nested ExpressionsTests for nested expressions.✅
Complex ExpressionsTests for complex expressions with multiple types of operators.✅
Error HandlingTests for error handling in expressions.✅

Documentation Coverage

The TinyExpr package is well-documented, with detailed explanations of the available features, usage examples, and API reference. The documentation covers:

Documentation SectionDescriptionStatus
OverviewOverview of the TinyExpr package✅
Features and LimitationsFeatures and limitations of the TinyExpr package✅
Getting Started GuideGuide to get started with TinyExpr✅
Usage ExamplesExamples of how to use TinyExpr✅
Available OperationsList of available operations in TinyExpr✅
API ReferenceAPI reference for the TinyExpr class and its methodsAPI Reference

Future Plans

Future plans for the TinyExpr package include:

  • Adding support for more advanced mathematical functions (e.g., hyperbolic trigonometric functions, special functions).
  • Improving performance for complex expressions.
  • Adding support for user-defined functions.
  • Enhancing error handling and reporting.
  • Providing more usage examples and documentation.
  • Adding support for additional mathematical constants.
  • Adding support for more extension methods.

Additional information

For more information, visit the TinyExpr GitHub repository.

To contribute to the package, please submit a pull request or file an issue on GitHub. We welcome contributions and will respond to issues as quickly as possible.

If you encounter any problems or have any questions, feel free to open an issue on GitHub. We aim to provide timely and helpful responses to all inquiries.