Flutter表达式计算插件tiny_expr的使用

简介

TinyExpr 是一个轻量级的 Dart 表达式求值库，旨在从字符串中评估数学表达式。这使得它成为需要动态计算的应用程序的理想选择。

该项目灵感来自于C语言编写的 TinyExpr 库，原库可以在这里找到。我们对原作者的杰出工作表示感谢。

功能特性

• 从字符串中评估数学表达式。
• 支持基本算术运算：加法、减法、乘法和除法。
• 支持括号以定义操作优先级。
• 支持指数运算。
• 支持一元取反。
• 支持常数（如 pi，e）。
• 支持三角函数（如 sin，cos，tan，cosec，sec，cot）。
• 支持双曲函数（如 sinh，cosh，tanh）。
• 支持对数函数（如 log，ln）。
• 支持平方根和绝对值。
• 支持指数函数。
• 支持舍入函数（如 ceil，floor）。
• 支持阶乘、组合（nCr）和排列（nPr）。
• 轻量且易于集成。
• 支持在 String 上扩展方法以直接使用 .evaluate() 方法。

入门指南

要开始使用 TinyExpr，请在 pubspec.yaml 文件中添加它作为依赖项：

dependencies:
  tiny_expr: ^0.3.1

然后运行 flutter pub get 来安装该包。

使用方法

简单实现

以下是如何使用 TinyExpr 评估表达式的简单示例：

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
}

使用变量

以下是如何使用 TinyExpr 带有变量的示例：

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

  // 更新变量值
  te.updateVariables({'x': 10.0});
  final updatedResult = te.evaluate();
  print('Updated Result: $updatedResult'); // Output: Updated Result: 20.0
}

使用扩展方法

TinyExpr 现在支持在 String 上扩展方法以直接评估表达式：

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
}

更多示例可以在 /example 文件夹中查看。

可用操作

测试覆盖范围

TinyExpr 包含全面的测试，以确保表达式评估的正确性。测试涵盖以下内容：

• 基本算术
• 指数运算
• 括号和优先级
• 一元取反
• 常数
• 三角函数
• 双曲函数
• 对数函数
• 平方根和绝对值
• 指数函数
• 舍入函数
• 阶乘
• 组合和排列
• 变量处理
• 嵌套表达式
• 复杂表达式
• 错误处理

文档覆盖范围

TinyExpr 包文档齐全，包含详细的功能说明、使用示例和 API 参考。文档涵盖以下部分：

• 概述
• 功能和限制
• 入门指南
• 使用示例
• 可用操作
• API 参考

未来计划

未来的计划包括：

• 添加更多高级数学函数（如双曲三角函数、特殊函数）
• 提高复杂表达式的性能
• 添加用户自定义函数的支持
• 增强错误处理和报告
• 提供更多使用示例和文档
• 添加更多数学常数的支持
• 添加更多扩展方法

更多信息

更多信息请访问 TinyExpr GitHub 仓库。

要为这个包做贡献，请提交 pull request 或者在 GitHub 上提交问题。我们欢迎贡献，并将尽快响应问题。

如果您遇到任何问题或有任何疑问，请随时在 GitHub 上提交问题，我们将尽力提供及时的帮助。

示例代码

以下是完整的示例代码，用于测试 TinyExpr 的各种功能：

import 'dart:math';
import 'package:tiny_expr/tiny_expr.dart';

void main() {
  // 测试 TinyExpr 评估器，给定表达式和预期结果
  void testExpression(String expression, double expected,
      {bool approx = false}) {
    try {
      final te = TinyExpr(expression);
      final result = te.evaluate();

      if (approx) {
        // 对于近似比较（例如浮点结果）
        if ((result - expected).abs() < 1e-6) {
          print("✅ Passed: $expression = $result (expected: $expected)");
        } else {
          print("❌ Failed: $expression = $result (expected: $expected)");
        }
      } else {
        // 对于精确比较
        if (result == expected) {
          print("✅ Passed: $expression = $result");
        } else {
          print("❌ Failed: $expression = $result (expected: $expected)");
        }
      }
    } catch (e) {
      print("❌ Failed: $expression threw an error: $e");
    }
  }

  // 运行所有测试
  print("Starting tests...\n");

  // 基本算术
  testExpression("2 + 3", 5.0);
  testExpression("10 - 4", 6.0);
  testExpression("6 * 7", 42.0);
  testExpression("20 / 5", 4.0);
  testExpression("8 % 3", 2.0);

  // 指数运算
  testExpression("2^3", 8.0);
  testExpression("5^0", 1.0);

  // 括号和操作优先级
  testExpression("(2 + 3) * 4", 20.0);
  testExpression("2 + 3 * 4", 14.0);
  testExpression("(2 + 3)^2", 25.0);

  // 一元取反
  testExpression("-5", -5.0);
  testExpression("-(2 + 3)", -5.0);

  // 常数
  testExpression("pi", pi, approx: true);
  testExpression("e", e, approx: true);

  // 三角函数
  testExpression("sin(pi / 2)", 1.0, approx: true);
  testExpression("cos(pi)", -1.0, approx: true);
  testExpression("tan(pi / 4)", 1.0, approx: true);
  testExpression("atan2(1, 1)", pi / 4, approx: true);
  testExpression("cosec(pi / 2)", 1.0, approx: true);
  testExpression("sec(0)", 1.0, approx: true);
  testExpression("cot(pi / 4)", 1.0, approx: true);

  // 双曲函数
  testExpression("sinh(1)", sinh(1.0), approx: true);
  testExpression("cosh(1)", cosh(1.0), approx: true);
  testExpression("tanh(1)", tanh(1.0), approx: true);

  // 对数函数
  testExpression("log(100)", 2.0);
  testExpression("ln(e)", 1.0, approx: true);

  // 平方根和绝对值
  testExpression("sqrt(16)", 4.0);
  testExpression("abs(-5)", 5.0);

  // 指数函数
  testExpression("exp(1)", e, approx: true);

  // 舍入函数
  testExpression("ceil(2.1)", 3.0);
  testExpression("floor(2.9)", 2.0);

  // 阶乘
  testExpression("fac(5)", 120.0);
  testExpression("fac(0)", 1.0);
  testExpression("fac(1)", 1.0);
  testExpression("5!", 120.0); // 阶乘运算符示例
  testExpression("0!", 1.0); // 阶乘运算符示例
  testExpression("1!", 1.0); // 阶乘运算符示例

  // 组合（nCr）和排列（nPr）
  testExpression("ncr(5, 3)", 10.0);
  testExpression("npr(5, 2)", 20.0);

  // 变量
  try {
    final teWithVars = TinyExpr("x + y * z");
    teWithVars.addVariables({"x": 3.0, "y": 2.0, "z": 5.0});
    final result = teWithVars.evaluate();
    if (result == 13.0) {
      print("✅ Passed: x + y * z with variables = $result");
    } else {
      print("❌ Failed: x + y * z with variables = $result (expected: 13.0)");
    }

    // 更新变量值
    teWithVars.updateVariables({"x": 10.0});
    final updatedResult = teWithVars.evaluate();
    if (updatedResult == 20.0) {
      print("✅ Passed: Updated x = $updatedResult");
    } else {
      print("❌ Failed: Updated x = $updatedResult (expected: 20.0)");
    }
  } catch (e) {
    print("❌ Failed: Variable tests threw an error: $e");
  }

  // 嵌套表达式
  testExpression("fac(3) + ncr(5, 2) * sqrt(16)", 6 + 10 * 4);

  // 复杂表达式
  testExpression("2 + 3 * (4 - 1)^2 / 2", 15.5);
  testExpression("5! + 3^2 - sqrt(16) * log(100)", 120.0 + 9 - 4 * 2);
  testExpression("sin(pi / 2) + cos(0) * tan(pi / 4)", 1.0 + 1.0 * 1.0,
      approx: true);
  testExpression("exp(1) + ln(e) - fac(3)", e + 1.0 - 6.0, approx: true);
  testExpression("ceil(2.1) + floor(2.9) * abs(-5)", 3.0 + 2.0 * 5.0);

  // 错误处理
  try {
    TinyExpr("unknown").evaluate();
    print("❌ Failed: Unknown variable/function should throw error");
  } catch (e) {
    print("✅ Passed: Unknown variable/function error handled: $e");
  }

  try {
    TinyExpr("5 +").evaluate();
    print("❌ Failed: Incomplete expression should throw error");
  } catch (e) {
    print("✅ Passed: Incomplete expression error handled: $e");
  }

  try {
    TinyExpr("log(-1)").evaluate();
    print("❌ Failed: log(-1) should throw error or return NaN");
  } catch (e) {
    print("✅ Passed: log(-1) error handled: $e");
  }

  print("\nAll tests completed!");
}

希望这些内容能帮助您更好地理解和使用 TinyExpr 插件！