Skip to content

Commit

Permalink
Merge pull request #725 from sys27/dev
Browse files Browse the repository at this point in the history
xFunc 4.4.0
  • Loading branch information
sys27 authored Sep 13, 2023
2 parents 076a211 + da4ee36 commit 108f240
Show file tree
Hide file tree
Showing 481 changed files with 13,043 additions and 8,270 deletions.
48 changes: 48 additions & 0 deletions .github/workflows/github-pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: Deploy static content to Pages

on:
push:
branches: ["dev"]

workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: "pages"
cancel-in-progress: false

jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0

- uses: actions/setup-dotnet@v3
with:
dotnet-version: '7.x'

- run: dotnet build -c Release xFunc.sln
- run: dotnet tool update -g docfx
- run: docfx docs/docfx.json

- name: Setup Pages
uses: actions/configure-pages@v3

- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: './docs/_site/'

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
8 changes: 8 additions & 0 deletions .vscode/tasks.json
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,14 @@
"-p:CollectCoverage=true"
],
"problemMatcher": "$msCompile"
},
{
"label": "Generate Documentation",
"command": "docfx",
"type": "process",
"args": [
"docs/docfx.json"
]
}
],
"inputs": [
Expand Down
14 changes: 7 additions & 7 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@
<ItemGroup>
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="1.1.1" />
<PackageVersion Include="Nerdbank.GitVersioning" Version="3.6.133" />
<PackageVersion Include="NSubstitute" Version="5.1.0" />
<PackageVersion Include="NUnit" Version="3.13.3" />
<PackageVersion Include="NUnit.Analyzers" Version="3.6.1" />
<PackageVersion Include="NUnit3TestAdapter" Version="4.5.0" />
<PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.507" />
<PackageVersion Include="System.Collections.Immutable" Version="7.0.0" />
<PackageVersion Include="CommandLineParser" Version="2.9.1" />
<PackageVersion Include="BenchmarkDotNet" Version="0.13.7" />
<PackageVersion Include="BenchmarkDotNet" Version="0.13.8" />
<PackageVersion Include="coverlet.msbuild" Version="6.0.0" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.7.0" />
<PackageVersion Include="Moq" Version="4.18.4" />
<PackageVersion Include="ReportGenerator" Version="5.1.23" />
<PackageVersion Include="xunit" Version="2.5.0" />
<PackageVersion Include="xunit.analyzers" Version="1.2.0" />
<PackageVersion Include="xunit.runner.visualstudio" Version="2.5.0" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.7.2" />
<PackageVersion Include="ReportGenerator" Version="5.1.25" />
</ItemGroup>
</Project>
50 changes: 20 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
Master: [![Build Status](https://dev.azure.com/exit/xFunc/_apis/build/status/sys27.xFunc?branchName=master)](https://exit.visualstudio.com/xFunc/_build/latest?definitionId=4&branchName=master) [![codecov](https://codecov.io/gh/sys27/xFunc/branch/master/graph/badge.svg)](https://codecov.io/gh/sys27/xFunc)
Dev: [![Build Status](https://dev.azure.com/exit/xFunc/_apis/build/status/sys27.xFunc?branchName=dev)](https://exit.visualstudio.com/xFunc/_build/latest?definitionId=4&branchName=dev) [![codecov](https://codecov.io/gh/sys27/xFunc/branch/dev/graph/badge.svg)](https://codecov.io/gh/sys27/xFunc)
xFunc.Maths: [![NuGet](https://img.shields.io/nuget/v/xFunc.Maths.svg)](https://www.nuget.org/packages/xFunc.Maths) [![Downloads](https://img.shields.io/nuget/dt/xFunc.Maths.svg)](https://www.nuget.org/packages/xFunc.Maths)
xFunc.DotnetTool: [![NuGet](https://img.shields.io/nuget/v/xFunc.DotnetTool.svg)](https://www.nuget.org/packages/xFunc.DotnetTool)
xFunc.Cli: [![NuGet](https://img.shields.io/nuget/v/xFunc.Cli.svg)](https://www.nuget.org/packages/xFunc.Cli)

xFunc
=====

xFunc is a simple and easy to use application that allows you to build mathematical and logical expressions. It's written on C#. The library includes well-documented code that allows developers to parse strings to expression tree, to analyze (derivate, simplify) expressions by using lexer, parser and etc.
xFunc is a user-friendly C# library for constructing and manipulating mathematical and logical expressions. This lightweight library empowers developers to effortlessly parse strings into expression trees, analyze expressions (including derivatives and simplifications), and perform various mathematical operations.

xFunc is a small-sized and portable application that you can use to create complex mathematical expressions which will be automatically computed. It can be used by teachers and students alike.
xFunc is a versatile tool suitable for both educators and students, allowing the creation of complex mathematical expressions.

Note: The WPF application (xFunc UI) was migrated to a separate repository [xFunc.UI](https://github.com/sys27/xFunc.UI).

## Features:

* Calculating expressions ([supported functions and operations](https://github.com/sys27/xFunc/wiki/Supported-functions-and-operations));
* Calculating expressions ([supported functions and operators](https://sys27.github.io/xFunc/articles/supported-functions-and-operations.html));
* Supporting measures of angles;
* Derivative and simplifying expressions;
* Plotting graphs;
Expand All @@ -23,7 +23,7 @@ Note: The WPF application (xFunc UI) was migrated to a separate repository [xFun

## Usage

The main class of xFunc library is `Processor`.
The main class of xFunc library is `Processor`. Detailed documentation is located on [GitHub Pages](https://sys27.github.io/xFunc/articles/get-started.html).

### Processor

Expand Down Expand Up @@ -53,19 +53,17 @@ _Note: The `Parse` method won't simplify the expression automatically, it will r

**Solve:**

This method parses string expression (like the `Parse` method) and then calculates it (returns object which implements the `IResult` interface).

There are two overloads of this method (common and generic). The "common" returns just `IResult` (you can access result by `Result` property). The generic allows to return specific implementation of `IResult` (eg. `NumberResult`).
This method parses string expression (like the `Parse` method) and then calculates it (returns object which implements the `Result` abstract class).

```csharp
var processor = new Processor();
processor.Solve<NumberResult>("2 + 2"); // will return 4.0 (double)
// or
var result = processor.Solve("2 + 2");

processor.Solve("2 + 2").Result; // will return 4.0 (object)
Console.WriteLine(result); // 4.0
```

The `result` variable will contain `4` (as `NumberResult` which is the implementation of the `Result` class). It is a hand-made implementation of the discriminated union. The `Result` class provides the abstraction (root class) for DU, whereas implementation for each possible return type is dedicated to the appropriate nested result class. Check documentation for more examples: [Result](https://sys27.github.io/xFunc/api/xFunc.Maths.Results.Result.html), [Processor](https://sys27.github.io/xFunc/api/xFunc.Maths.Processor.html).

If your expression has any parameter, you need to assign a value to it (otherwise xFunc will throw an exception), because `Processor` has a build-in collection of parameters and user functions, you don't need to use `ExpressionParameters` directly:

```csharp
Expand All @@ -76,27 +74,25 @@ processor.Solve("x := 10");
processor.Parameters.Variables.Add("x", 10);
```

_Note: The `Solve` method automatically simplifies expression, to control this behavior you can use the `simplify` argument. It's useful for differentiation because it will eliminate unnecessary expression nodes._

**Simplify:**

```csharp
var processor = new Processor();

processor.Solve<ExpressionResult>("simplify((x) => arcsin(sin(x)))");
processor.Solve("simplify((x) => arcsin(sin(x)))");
// or
processor.Simplify("arcsin(sin(x))");
// will return simplified expression = "x"
```

_Detailed [simplification rules](https://github.com/sys27/xFunc/wiki/Simplification-rules)_
_Detailed [simplification rules](https://sys27.github.io/xFunc/articles/simplification-rules.html)_

**Differentiate:**

```csharp
var processor = new Processor();

processor.Solve<ExpressionResult>("deriv((x) => 2x)");
processor.Solve("deriv((x) => 2x)");
// or
processor.Differentiate("2x");
// will return "2"
Expand All @@ -117,28 +113,22 @@ processor.Differentiate("2x + sin(y)", new Variable("x")); // will return "2"
| Version | Method | Mean | Allocated |
|--------:|--------|--------------:|----------:|
| 3.7.3 | Parse | 39,567.9 ns | 63736 B |
| 4.0.0 | Parse | 9,128.180 ns | 4760 B |
| 4.2.0 | Parse | 14,855.62 ns | 4872 B |
| 4.3.0 | Parse | 10,434.04 ns | 4848 B |
| 3.7.3 | Solve | 55,260.0 ns | 96920 B |
| 4.0.0 | Solve | 15,319.497 ns | 10672 B |
| 4.2.0 | Solve | 22,074.89 ns | 9936 B |

[More details](https://github.com/sys27/xFunc/wiki/Performance-Comparison)
| 4.3.0 | Solve | 15,683.42 ns | 9552 B |

## Bug Tracker

Please, if you have a bug or a feature request, [create](https://github.com/sys27/xFunc/issues) a new issue. Before creating any issue, please search for existing issues.
[More details](https://sys27.github.io/xFunc/articles/performance-comparison.html)

## License

xFunc is released under MIT License.

## Thanks

[@RonnyCSHARP](https://github.com/ronnycsharp)

[Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/)
[Coverlet](https://github.com/coverlet-coverage/coverlet)
[ReportGenerator](https://github.com/danielpalme/ReportGenerator)
[xUnit](https://github.com/xunit/xunit)
[Moq](https://github.com/moq/moq4)
[NUnit](https://github.com/nunit/nunit)
[NSubstitute](https://github.com/nsubstitute/NSubstitute)
[docfx](https://github.com/dotnet/docfx)
[BenchmarkDotNet](https://github.com/dotnet/BenchmarkDotNet)
9 changes: 9 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
###############
# folder #
###############
/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
_site
5 changes: 5 additions & 0 deletions docs/api/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
###############
# temp file #
###############
*.yml
.manifest
130 changes: 130 additions & 0 deletions docs/articles/breaking-changes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
## xFunc 4.4.0

* The `Helpers` class is removed from the public API (see [#698](https://github.com/sys27/xFunc/pull/698)).
* `LambdaExpression` doesn't capture context on `Execute` this code moved to `CallExpression` (see [#704](https://github.com/sys27/xFunc/issues/704)).
* `xFunc.DotnetTool` -> `xFunc.Cli`
* `While` doesn't inherit `BinaryExpression`, instead it implements `IExpression` directly.
* `ResultIsNotSupportedException` -> `ExecutionException`. The error message changed.
* `While`/`For` throws the correct exception when `Condition` doesn't return `bool` (`InvalidCastException` -> `ExecutionException`).
* `While`/`For` returns `EmptyValue`.
* `Derivative`/`If`/`While`/`For` is executed in nested `ExpressionParameters` scope now. It means all variables created in process of expressions evaluation won't affect parent/global scope.
* The `Parameters` property is removed from `DifferentiatorContext`.
* The return type of `Processor.Solve` method has change (see [#720](https://github.com/sys27/xFunc/pull/720) - New Results API).

## xFunc 4.3.0

* `MatrixIsInvalidException` -> `InvalidMatrixException`.
* `Vector`/`Matrix` returns `VectorValue`/`MatrixValue` instead of `Vector`/`Matrix`.
* `Del`/`Simplify`/`Derivate` functions accept/return lambdas instead of expression.
* The grammar for `CallExpression`. Now you can use any expression as the function to call, eg. `deriv((x) => x ^ 2)(3)` because `deriv` returns a lambda, you can call it immediately. Previously, only user function and inline lambda expression were supported.
* `ExpressionResult` is removed, partially replaced by `LambdaResult`.
* `ResultTypes.Expression` and `ResultTypes.Lambda` are merged into `ResultTypes.Lambda`.
* DotNet Tool has the `xfunc` name in the terminal (all letters are lowercase).
* `NumberValue.NegativeInfinity` points to `double.NegativeInfinity` instead of `double.PositiveInfinity`.
* The ability to parse the implicit mull operator (eg. 2x) is returned.

## xFunc 4.2.0

* `xFunc.Maths` targets `.NET 6` instead of `.NET Standard 2.1`
* `ComplexNumber` doesn't perform the strict comparison of floating point numbers (Real and Imaginary parts).
* `AngleUnit` is `class` instead of `enum`.
* `Contains`/`ContainsKey` (`ParameterCollection`) doesn't check the constants collection anymore (see [#623](https://github.com/sys27/xFunc/issues/623)).
* Removed russian localization (see [#625](https://github.com/sys27/xFunc/issues/625)).
* `UserFunction` was removed, partially replaced by `CallExpression` and `Lambda` (see [#628](https://github.com/sys27/xFunc/issues/628)).
* `ParameterCollection` is renamed to `ExpressionParamaters`, and the old version of `ExpressionParameters` is removed.
* `FunctionCollection` was removed, now `ExpressionParameters` can hold functions as well (see [#628](https://github.com/sys27/xFunc/issues/628)).
* `->` and `=>` operators can be used only for lambda expressions, the implication and the equality operators can be used only by keywords: `impl` and `eq`.
* `Define`/`Undefine` can accept only `Variable` instead of `IExpression`.
* the grammar to define user function was changed from `f(x) := sin(x)` to `f := (x) => sin(x)`.
* `Define` -> `Assign`, `Undefine` -> `Unassign`.
* The `:=` operator and `assign`/`unassign` functions are parsed as expressions instead of statements (they can be used inside other expressions, for example: `1 + (x := 1)`/`(f := (x) => x)(2)`
* `Assign`/`Unassign` returns the assigned/unassigned value instead of `string`.
* The ability to parse the implicit mull operator (eg. `2x`) is removed. Now only `2 * x` is supported.

## xFunc 4.1.0

* `Analyzer<TResult, TContext>` is abstract now.
* UI moved to the separate repository [xFunc.UI](https://github.com/sys27/xFunc.UI).
* The `xFunc.UnitConverter` project was removed (unit conversion migrated to xFunc.Maths).

## xFunc 4.0.0

**The grammar is changed:**
* it is no longer "validated" by lexer/post processing, now it is a part of parsing process.
* `:=`, `def`, `undef` operators are statements now (so, they cannot be used as a parameter of any expression, execpt: 'for', 'while', 'if' or standalone usage).
* `for`, `while` functions are statements now.
* the `^` operator is right-associative (see [#244](https://github.com/sys27/xFunc/issues/244)).
* `vector`/`matrix` prefix is no longer required to create a vector/matrix, like: `{1, 2}`.
* functions should use parentheses (`(`, `)`), `{`, `}` is no longer supported.

**Lexer:**
* The lexer post processing is removed.
* The lexer factories are removed.
* `Functions`, `Symbols`, `Operators` enums are removed.
* `UserFunctionToken` is removed.
* Several operator tokens are moved to keywords.
* Lexer and Tokens are removed from public API (see [#311](https://github.com/sys27/xFunc/issues/311), [#312](https://github.com/sys27/xFunc/issues/312)).
* All Tokens are represented by single struct (see [#311](https://github.com/sys27/xFunc/issues/311)).

**Expressions:**
* Expressions are **immutable** ([#331](https://github.com/sys27/xFunc/issues/331)).
* Precedence of operators are changed ([#343](https://github.com/sys27/xFunc/issues/343)).
* Changed validation in expression constructors (no nulls, no empty arrays, strict parameter count).
* `IFunctionExpression` is removed.
* Changer order of parameters in `Log` constructor.
* `Inc`, `Dec` do not inherit `UnaryExpression`. The `Argument` property is renamed to `Variable` (type `Variable`).
* `AddAssign`, `SubAssign`, `MulAssign`, `DivAssign` do not inherit `BinaryExpression`. The `Left` property is renamed to `Variable` (type `Variable`).
* `UnaryExpression.Argument`, `BinaryExpression.Left/Right` are no longer virtual.
* `DifferentParametersExpression.Arguments`, `Matrix.Vectors` return `IEnumerable<IExpression>` instead of array and it is only getter now.
* `Matrix`, `Vector`, `DifferentParametersExpression` do not allow `null` arguments.
* `Matrix`, `UserFunction` do not inherit `DifferentParametersExpression`.
* `Matrix.CreateIdentity`, `Matrix.this[int row, int col]` are removed.
* `Matrix.ParametersCount` -> `Rows`.
* `Matrix.SizeOfVectors` -> `Columns`.
* `And`/`Or` (from `xFunc.Maths.Expressions.Programming` namespace) -> `ConditionalAnd`/`ConditionalOr`.
* Logical/Bitwise operators do not support floating point numbers (throw `ArgumentException` exception).
* The `Parent` property is removed from `IExpression` (see [#275](https://github.com/sys27/xFunc/issues/275)).
* Inverse trigonometric/hyperbolic expression return radians, use conversion functions (`todegree`, etc) to get other units (see [#268](https://github.com/sys27/xFunc/issues/268)).

**Other:**
* The expression factory is removed (moved to parser as internal part).
* Removed support for `.NET Framework`. `xFunc.Maths`/`xFunc.UnitConverters` is [.NET Standard 2.1](https://docs.microsoft.com/en-us/dotnet/standard/net-standard).
* Removed Ukranian localization.
* xFunc UI moved to .NET Core 3.1.
* `CLSCompliant` is removed.
* `GetHashCode` implementations are removed.
* `MathExtensions`, `ComplexExtensions`, `MatrixExtensions` are removed from public API.
* `Variable` and `Parameters` properties are moved from `Differentiator` to `DifferentiatorContext` (see [#277](https://github.com/sys27/xFunc/pull/277)).
* The constructor of `Bool` is private, use static fields `True`/`False`.
* `AngleMeasurement` moved to `Expression.Angles` namespace (see [#268](https://github.com/sys27/xFunc/issues/268)).
* The `AngleMeasurement` property is removed from `ExpressionParameters`, this feature is replaced by number units, which you can specify alongside a number, like `90 degree` (see [#268](https://github.com/sys27/xFunc/issues/268)).
* `NumeralSystem.Hexidecimal` -> `NumeralSystem.Hexadecimal`.
* `NumeralSystem` is removed (see [#302](https://github.com/sys27/xFunc/issues/302)).
* It is not allowed to assign an `object` to `Parameter` (it is removed from public API).

## xFunc 3.7.0

* All internal constructors of expression was removed (see [#216](https://github.com/sys27/xFunc/issues/216)).
* `ExpressionFactory` was reworked (see [#216](https://github.com/sys27/xFunc/issues/216)).
* `LexerException` -> `TokenizeException` (see [#216](https://github.com/sys27/xFunc/issues/216)).
* `ParserException` -> `ParseException` (see [#216](https://github.com/sys27/xFunc/issues/216)).
* The `DoSimplify` property was removed (see [#220](https://github.com/sys27/xFunc/issues/220)).
* The setter for `Type` property of `Parameter` was removed.
* `Parameter` cannot contain `null` value (see [#222](https://github.com/sys27/xFunc/issues/222)).
* The value of `Parameter` (Constant or ReadOnly) cannot be changed (see [#222](https://github.com/sys27/xFunc/issues/222)).
* Max/MinParameters are removed (see [#223](https://github.com/sys27/xFunc/issues/223)).
* `FunctionToken.CountOfParams` -> `FunctionToken.CountOfParameters`

## xFunc 3.6.0

* `MinParameters`, `MaxParameters`, `ParametersCount` moved from `IExpression` to `IFunctionExpression` (see [#211](https://github.com/sys27/xFunc/issues/211)).

## xFunc 3.5.0

* Changed exceptions, which are thrown by Expressions and Type Analyzer (see [#190](https://github.com/sys27/xFunc/issues/170)).
* Removed ReverseFunctionAttribute (see [#195](https://github.com/sys27/xFunc/issues/195)).
* Variables and user functions are case sensitive (see [#197](https://github.com/sys27/xFunc/issues/197)).

## xFunc 3.2.1

* Removed `Processor.Parse(string, bool)` method (see [#170](https://github.com/sys27/xFunc/issues/170)). Add new property to control simplification of expression: `bool Processor.DoSimplify`.
Loading

0 comments on commit 108f240

Please sign in to comment.