1.4.0

CHANGELOG.md

@@ -1,52 +1,86 @@
+# 1.4.0
+
+## Custom Functions
+
+- Define custom functions and redefine built-in functions when parsing
+  an expression. See docs and example.
+- Use `MathNodeExpression.getPotentialFunctionNames()` to detect potentially
+  used functions in a string.
+- Use period in the middle of custom variable and function names.
+- Under-hood, functions now support multiple comma separated arguments, so
+  you can supply multiple arguments to your custom function.
+- Detect custom functions im math tree using
+  `MathExpression.getUsedFreeformFunctions()`.
+
+## Breaking changes
+
+- `MissingFunctionArgumentListException` renamed to
+  `OutOfRangeFunctionArgumentListException`
+- `MathNodeExpression.fromString()` may throw other errors besides
+  `MathException`
+- `MathNodeExpression.getPotentialVariableNames()` is replaced by
+  `MathNodeExpression.getPotentialDefinable()`
+- Instead of `log[base](arg)`, you should pass `log(base, arg)` syntax now
+- Period is an allowed character in the middle of a variable name now
+
+## Misc.
+
+- `UnexpectedClosingBracketException` and `BracketsNotClosedException` can
+  now tell where the problem probably happened.
+- New MathParseException's `InvalidFunctionNameException`,
+  `DuplicateDeclarationException`, `InvalidFunctionArgumentsDeclaration`.
+
 # 1.3.1
+
 - Variable validation fix
 
 # 1.3.0
 
 ## Math Tree
-- Important change: `MathNode` is now a class of `MathExpression` interface. 
+
+- Important change: `MathNode` is now a class of `MathExpression` interface.
   Compared to MathNode, MathExpression may return null in `calc()` method.
 - New: `getUsedVariables()` method for `MathExpression` and `MathNode`.
   This method goes down the math tree to find any uses of `MathVariable`
   and returns names of all variables.
 - New: `MathExpression` object family - `MathComparison`:
-    - `MathComparisonEquation` (=)
-    - `MathComparisonGreater` (>)
-    - `MathComparisonLess` (<)
+  - `MathComparisonEquation` (=)
+  - `MathComparisonGreater` (>)
+  - `MathComparisonLess` (<)
 
 ## Parsing
-- New: `MathNodeExpression.fromStringExtended()` method allows you to 
-  interpret equations and comparisons. Compared to `fromString`, 
+
+- New: `MathNodeExpression.fromStringExtended()` method allows you to
+  interpret equations and comparisons. Compared to `fromString`,
   it returns `MathExpression` instead of `MathNode`, since comparisons
   can't guarantee result.
 - New: `MathNodeExpression.getPotentialVariableNames()` analyzes given
-  math expression string for possible use of variables. Refer to 
+  math expression string for possible use of variables. Refer to
   documentation for rough edges before using it.
 - New: `MathNodeExpression.builtInVariables` gives a list of built-in
   predefined variable names.
-- New: `MathNodeExpression.isVariableNameValid()` lets you check if 
+- New: `MathNodeExpression.isVariableNameValid()` lets you check if
   the parser can work with a given name.
 
 ## Misc.
+
 - Changed input parameters type for `CantProcessExpressionException`.
 - Small documentation fixes.
 
 # 1.2.0
 
 - Fix README.
-- Moved integrating features to a separate package library 
+- Moved integrating features to a separate package library
   `math_parser_integrate`.
 
-
 # 1.1.0
 
 - Custom variables support.
 - `MathFunctionX`deprecated.
 - `MathVariable` introduced.
-- You need to pass an instance of `MathVariableValues` instead of a num 
+- You need to pass an instance of `MathVariableValues` instead of a num
   to the `calc()` function now.
 
-
 # 1.0.0
 
 - Initial version.

README.md

@@ -50,9 +50,14 @@ The library can parse general mathematical expressions strings
 and return them as a machine-readable `MathNode` using
 `MathNodeExpression.fromString` method.
 
-- Set `isMinusNegativeFunction` to `true` to interpret minus operator as a
-  sum of two values, right of which will be negative: X - Y turns to X + (-Y)
-- Set `isImplicitMultiplication` to `false` to disable implicit multiplication
+Define custom variables with `variableNames` parameter. Don't forget to
+define the variable value in `MathExpression.calc` when calling it.
+
+Define custom functions using `customFunctions` argument. You can use either
+`MathCustomFunctions` class, which plainly declares the functions, or
+`MathCustomFunctionsImplemented`, which also requires to implement the
+function. When you use `MathCustomFunctionsImplemented` during parsing,
+you don't need to redeclare the function in `MathExpression.calc`.
 
 ### Parse priority:
 
@@ -61,11 +66,14 @@ and return them as a machine-readable `MathNode` using
    by default, but you can override this behavior with the variableNames
    parameter. You can rewrite e and pi by defining it in variableNames and
    mentioning it during the calc call.
-   First character must be a letter, others - letters, digits, or
-   underscore. Letters may be latin or Greek, both lower or capital case.
-   You can't use built-in function names like sin, cos, etc. Variable names
-   are case-sensitive
+   First character must be a letter or \_, others - letters, digits, period,
+   or underscore. Last symbol can't be a period. Letters may be latin or
+   Greek, both lower or capital case. You can't use built-in function
+   names like sin, cos, etc. Variable names are case-sensitive. Custom
+   functions have the same requirements, except they can override built-in
+   functions.
 3. Functions (case-sensitive):
+   - Custom functions
    - sin, cos, tan (tg), cot (ctg)
    - sqrt (√) (interpreted as power of 1/2), complex numbers not supported
    - ln (base=E), lg (base=2), log\[base\]\(x\)
@@ -89,11 +97,13 @@ MathNode fromString(
 
     /// Expressions which should be marked as variables
     Set<String> variableNames = const {'x'},
+
+    /// Expressions which should be marked as functions
+    MathCustomFunctions customFunctions = const MathCustomFunctions({}),
   });
 ```
 
-Example for parsing a string and evaluating it with `x = 20`
-and `y = 5`:
+Example for parsing a string and evaluating it with `x = 20`:
 
 ```dart
 final expression = MathNodeExpression.fromString(
@@ -103,7 +113,8 @@ final expression = MathNodeExpression.fromString(
 );
 ```
 
-More complicated work with variables is shown off in example.
+More complicated work with variables and functions is shown off in
+example.
 
 You can also parse equations with `MathNodeExpression.fromStringExtended`,
 refer to example for this.