Awesome

Contents

1. Introduction

2. Quickstart

3. About the project<br />     3.1. Design goals<br />     3.2. Roadmap<br />     3.3. Contributing<br />     3.4. Documentation<br />     3.5. Releases<br />     3.6. Changelog<br />

4. Jodosoft.Numerics<br />     4.1. Fixed-point numbers<br />     4.2. Non-overflowing numbers<br />     4.3. Framework for numbers<br />     4.4. Structures<br />     4.5. Random extensions<br />     4.6. Performance considerations<br />

5. Jodosoft.Geometry (preview)<br />

6. Jodosoft.Collections (preview)<br />

7. Jodosoft.Primitives<br />     7.1. Random variants<br />     7.2. Default providers<br />     7.3. Shims<br />     7.4. Binary IO Extensions<br />

1. Introduction <br id="introduction" />

Welcome to The Jodosoft Libraries, a project to make simple, reliable .NET libraries covering numerics, geometry and data structures.

This document describes the goals of the project, the features of each library, and steps for getting started.

[Back to top]

2. Quickstart <br id="quickstart" />

To install a Jodosoft library, use your NuGet package manager or run <a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package">dotnet add</a>, e.g.

No configuration or dependency injection is required. Simply import the relevant Jodosoft namespace and begin using the types in your code.

Most platforms and versions of .NET are supported, and the libraries can be used freely in commercial work under the terms of the MIT License.

The available libraries are:

• Jodosoft.Numerics - extra number types (such as fixed-point and non-overflowing) that support maths, string-parsing, operators and more.
• Jodosoft.Geometry (preview) - shapes, angles and trigonometric functions that work with number types from Jodosoft.Numerics
• Jodosoft.Collections (preview) - data-structures, utilities and collection abstractions
• Jodosoft.Primitives - utilities and abstractions used throughout the Jodosoft libraries

[Back to top]

3. About the project <br id="about" />

The Jodosoft Libraries started as a collection of classes from the personal projects of Joe Lawry-Short. The types have been reorganized, refactored, and tested rigorously with the aim of making them useful for the .NET community.

This section describes the design goals, roadmap, and other details of the project.

[Back to top]

3.1. Design Goals <br id="design-goals" />

The table below summarizes the design goals of the project.

[Back to top]

3.2. Roadmap <br id="roadmap" />

The table below summarizes the high-level development goals for upcoming versions of the Jodosoft Libraries.

[Back to top]

3.3. Contributing <br id="contributing" />

Community contributions are welcome at https://github.com/Jodosoft/Libraries (the home of this repository). A list of reported issues can be found at <a href="https://github.com/Jodosoft/Libraries/issues">https://github.com/Jodosoft/Libraries/issues</a>. Contributors are requested to adhere to the <a href="CODE-OF-CONDUCT.md">code of conduct</a>.

This work is licensed under the <a href="LICENSE.md">MIT License</a>.

[Back to top]

3.4. Documentation <br id="documentation" />

[Back to top]

3.5. Releases <br id="releases" />

[Back to top]

3.6. Changelog <br id="changelog" />

The following table summarizes the changes that were made for each published version of the Jodosoft Libraries.

[Back to top]

4. Jodosoft.Numerics <br id="numerics" />

Provides custom number types, numeric utilities, and a generic interface for defining numbers.

<a href="https://www.nuget.org/packages/Jodosoft.Numerics/"><img alt="Nuget (with prereleases)" src="https://img.shields.io/nuget/vpre/Jodosoft.Numerics?label=version&style=flat-square&color=005784&logo=nuget&no-cache"></a>

[Back to top]

4.1. Fixed-point numbers <br id="numerics-fixed-point-numbers" />

Unlike floating-point numbers, <a href="https://en.wikipedia.org/wiki/Fixed-point_arithmetic">fixed-point numbers</a> maintain a constant degree of precision regardless of magnitude. This can be useful in situations where <a href="https://en.wikipedia.org/wiki/MIM-104_Patriot#Failure_at_Dhahran">precision remains important whilst numbers grow</a>. As a trade-off, fixed-point numbers have a much lower maximum magnitude than floating-point numbers of the same size.

<a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_Fix64.htm">Fix64</a> and <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_UFix64.htm">UFix64</a> are fixed-point number types with 6 decimal digits of precision. As with all number types provided by this library, they support a full range of mathematical functions, operators, conversions, string formatting, etc. (see <a href="#numerics-framework-for-numbers">§4.3. Framework for numbers</a>).

The table belows summarizes the capabilities of these types.

[Back to top]

4.2 Non-overflowing numbers <br id="numerics-non-overflowing-numbers" />

Number types in the <a href="https://libraries.jodosoft.com/docs/api/N_Jodosoft_Numerics_Clamped.htm">Jodosoft.Numerics.Clamped</a> namespace have built-in prevention of overflow. Operations that would normally error or overflow instead return MinValue or MaxValue, and operations that would normally return <code>NaN</code> instead return zero.

This provides an alternative to using the <a href="https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/checked-and-unchecked"><code>checked</code></a> keyword, removing the need for repetitive error handling logic.

As with all number types provided by this library, non-overflowing number types support a full range of mathematical functions, operators, conversions, string formatting, etc. (see <a href="#numerics-framework-for-numbers">§4.3. Framework for numbers</a>).

var i = Int32M.MaxValue + 1;
Console.WriteLine(i);  // output: 2147483647

var f = (SingleM)4 / 0;
Console.WriteLine(f);  // output: 3.402823E+38

The table below summarizes the non-overflowing number types and utilities provided by this library:

[Back to top]

4.3. Framework for numbers <br id="numerics-framework-for-numbers" />

The <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_INumeric_1.htm">INumeric<TSelf></a> interface provides a definition for number types with support for operators, maths, string-conversion, random generation, and more.

Static utility classes, such as <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_MathN.htm">MathN</a> and <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_ConvertN.htm">ConvertN</a>, expose these features in a way that is similar to .NET API.

The table below gives a full list of features supported by number types that implement <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_INumeric_1.htm">INumeric<TSelf></a>.

Console.WriteLine($"{var1:N}"); // outputs: 1,023.00 Console.WriteLine($"{var1:X}"); // outputs: 3FF Console.WriteLine($"{var2:E}"); // outputs: 9.954322E+001 Console.WriteLine($"{var2:000.000}"); // outputs: 099.543</code></pre>

Console.WriteLine(var1); // outputs: 0.405808417991177 (example) Console.WriteLine(var2); // outputs: 102.85086051826445 (example)</code></pre>

Console.WriteLine(result); // output: 3.141</code></pre>

[Back to top]

4.4. Structures <br id="numerics-structures" />

Numeric structures, such as vectors, are provided for use in mathematical applications. These structures are generic on number type, supporting any implementation of <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_INumeric_1.htm">INumeric<TSelf></a> (see <a href="#numerics-framework-for-numbers">§4.3. Framework for numbers</a>). The table below summarizes the available structs and accompanying utilities.

[Back to top]

4.5. Random extensions <br id="numerics-random-extensions" />

Extension methods for <a href="https://docs.microsoft.com/en-us/dotnet/api/system.random">System.Random</a> add support for generating every built-in number type and types that implement <a href="https://libraries.jodosoft.com/docs/api/T_Jodosoft_Numerics_INumeric_1.htm">INumeric<TSelf></a> (see <a href="#numerics-framework-for-numbers">§4.3. Framework for numbers</a>).

Overloads are provided that allow greater flexibility with bounds via the Generation enum:

using Jodosoft.Numerics;
using System;

var value1 = new Random().NextDouble(double.MinValue, double.MaxValue); // Returns any finite double.
var value2 = new Random().NextUInt64(200, 100, Generation.Extended); // Returns a ulong between 100 and 200 (inclusive).

[Back to top]

4.6 Performance considerations <br id="numerics-performance-considerations" />

The number types provided by this library are structs that wrap built-in types and operations. Therefore they require additional memory and CPU time compared to using the built-in types alone.

Additionally, the number types within the Jodosoft.Numerics.Clamped namespace make use of the checked keyword for conversion and arithmetic. This further increases CPU time compared to using unchecked operations, especially in cases of overflow.

If developing a performance-sensitive application, use a profiler to assess the impact of introducing these types. Generally speaking, the impact is likely to be acceptable unless CPU-bound arithmetic is already on the hot path for the given application (e.g. in machine learning or 3D physics applications).

Benchmarks are provided to facilitate comparison with the built-in number types. To run the benchmarks, clone this repository then build and run Jodosoft.Numerics.Benchmarks in RELEASE mode (without a attaching a debugger).

Sample output can be seen below:

Jodosoft.Numerics.Benchmarks - Results from 2022-09-28 07:58:50Z

• Processor: 11th Gen Intel(R) Core(TM) i7-11800H @ 2.30GHz
• Architecture: x64-based processor
• .NET Version: .NET 5.0.17
• Architecture: X64
• OS: win10-x64
• Seconds per Benchmark: 60.0

[Back to top]

5. Jodosoft.Geometry (preview) <br id="geometry" />

Provides geometric structs and utilities that support custom number types.

Coming soon (see section 2.2. "Roadmap")

[Back to top]

6. Jodosoft.Collections (preview) <br id="collections" />

Provides extra collection classes and interfaces to complement the .NET API.

Coming soon (see section 2.2. "Roadmap")

[Back to top]

7. Jodosoft.Primitives <br id="primitives" />

Provides utilities and abstractions that are used throughout the Jodosoft Libraries.

<a href="https://www.nuget.org/packages/Jodosoft.Primitives/"><img alt="Nuget (with prereleases)" src="https://img.shields.io/nuget/vpre/Jodosoft.Primitives?label=version&style=flat-square&color=005784&logo=nuget&no-cache"></a>

[Back to top]

7.1. Random variants <br id="primitives-random-variants" />

Provides a specification for randomly generating objects based on variants (described below). This feature is used extensively by the Jodosoft test libraries to ensure that tests cover a variety of scenarios. Although the exact definition of each variant is left to the implementor, the following table serves as a guide:

Extension methods are provided for <a href="https://docs.microsoft.com/en-us/dotnet/api/system.random">System.Random</a> to enable random generation of values within each variant.

[Back to top]

7.2. Default providers <br id="primitives-default-providers" />

Documentation tbc

[Back to top]

7.3. Shims <br id="primitives-shims" />

Documentation tbc

[Back to top]

7.4. Binary IO extensions<br id="binary-IO-extensions" />

Documentation tbc

[Back to top]