Repository files navigation

A comprehensive fixed-point math library written in C++23 and C++17, designed for high precision and efficiency.

• master contains version 2.x rewritten in c++23
• branch 1.x contains stable c++17 which will be still maintained for compatibility and bugfixes

• version 2.x requires C++23 standard to compile while 1.x only C++17
• version 2.x version has both math functions avaiable as plain functions and as function objects, while 1.x only as plain functions
• version 2.x has much more constraints for validity of types checking at compile time compared to 1.x and exploits C++23 standard
• API is a bit different in version 2.x as plain functions in 2.x comapred to 1.x are defined in sub namespacefixedmath::func and function objects in sub namespacefixedmath::fobj, however You can usenamesapce fixedmath{ using namesapce fixedmath::func; } for getting backward compatibility.
• version 2.x is tested with every PR if it works with clang libstdc++, clang libc++, gcc, msvc, msvc clang-cl compilers

• Modern C++ Standards: Requires a minimum of C++23, (branch 1.x c++17) leveraging modern language features for optimal performance and reliability.
• Strongly Typed Fixed-Point Arithmetic: Utilizes a 48.16 fixed-point arithmetic model, ensuring type safety with explicit conversions and operations. Thefixed_t type is robust against unintentional type conversions, fostering code correctness.
• Implicit Type Promotion: Supports implicit promotion of all arithmetic types (excludingdouble) tofixed_t in basic arithmetic operations, enhancing ease of use without sacrificing precision.
• Double Precision Compatibility: Interactions betweenfixed_t anddouble types automatically yield adouble result type. Arithmetic operations involvingdouble are seamlessly elevated to double precision, ensuring accuracy for critical calculations.
• Compile-Time Evaluation: The entire codebase, including trigonometric functions, isconstexpr, enabling compile-time evaluations where applicable. This feature significantly reduces runtime overhead and allows for constant expressions.[1]
• Header-Only Library: As a fully header-only library with extensive use ofconstexpr, FixedMath simplifies integration into projects. Explore the API interface and implementation details:API Reference |Implementation.
• Compile-Time Unit Testing: Offers a robust suite of compile-time unit tests, streamlining test-driven development and ensuring library correctness. Dive into the unit tests:Compile-Time Unit Tests.

FixedMath is committed to delivering precision, efficiency, and ease of use, making it an ideal choice for projects requiring fixed-point arithmetic in a modern C++ environment.

[1] Thesqrt function is always available asconstexpr, utilizing the Abacus algorithm for constant evaluation, alongside the standardstd::sqrt for runtime execution. On windows msvc toolset (not clang-cl) still is not fully compatibile with c++23 and still has nonsense compiletime evaluation errors,for example I had to split consteval function into constant but this change does not has any sense.

At this stage, the code has not been optimized, and the results presented below are based solely on initial implementations focused on code quality. The performance metrics indicate the relative computation times for executing functions across a large dataset of input values, without considering value conversions.

Cortex-A73 - Snapdragon 865+

Ryzen 9 - 3900X

This library is predominantly header-only, with the exception of tabularized trigonometric functions. Therefore, if you require only the precise trigonometric functions, there is no need for compilation. Simply addfixed_lib/include to your include path and use#include <fixedmath/fixed_math.hpp> in your code.

For access to additional, approximate trigonometric functions, the library should be compiled like any standard CMake project. Currently, the project does not offer any specific tuning parameters for CMake.

For projects utilizing CPM (CMake Package Manager) for dependency management, you can easily integrate FixedMath by adding the following lines to yourCMakeLists.txt:

CPMAddPackage(NAME fixed_math  GITHUB_REPOSITORY arturbac/fixed_math  GIT_TAG        v2.0.0)find_package(fixed_math REQUIRED)# optional PCHtarget_precompile_headers( fixed_mathINTERFACE <fixedmath/fixed_math.hpp>)

The following compilers are confirmed to compile the project in branches

• Clang version 18.0.1 with llvm-libcxx on Gentoo x86-64
• Clang version 18.0.1 with gcc-libstdc++ 14.1.1 on Gentoo x86-64
• Clang version 18 on ubuntu-24.04
• GCC 14.1.1_p20240720 p4 on Gentoo x86-64
• GCC 14.0.1 on ubuntu-24.04
• MSVC ClanCL-toolset 17.0.3 from MSVC 19.40.33813.0
• MSVC toolset 19.40.33813.0

• Clang 18.0.1 with llvm-libcxx on Gentoo x86-64
• Clang 17.0.6 with llvm-libcxx on Gentoo x86-64
• Clang 13.0.0 with llvm-libcxx on Gentoo x86-64
• Clang 13.0.0 with gcc-libstdc++ 11.2.1 on Gentoo x86-64
• Clang 12.0.1 with llvm-libcxx on FreeBSD 13 x86-64
• Clang 11.0.1 with gcc-libstdc++ 10.2.0 on Gentoo Linux x86-64 and aarch64
• Clang 11.0.1 with llvm-libcxx on x86-64
• Clang 10.0.1 with llvm-libcxx on FreeBSD 13 x86-64
• GCC 14.1.1_p20240720 p4 on Gentoo x86-64
• GCC 13.2.1_p20240210 p13 on Gentoo x86-64
• GCC 12.3.1_p20240209 p2 on Gentoo x86-64
• GCC 11.2.1 20211127 on Gentoo x86-64
• GCC 10.2.0 on x86-64 on Gentoo x86-64
• GCC 9.4.0 on Gentoo x86-64
• MSVC 19 (Visual Studio 2019) support

If you encounter any issues, please report it by submitting an issue.

fixed_t serves as the typename for the fixed-point arithmetic type within this library, supporting common operators such as+,-,*, and more.

#include<fixedmath/fixed_math.hpp>#include<fixedmath/iostream.h>using fixedmath::fixed_t;using fixedmath::operator""_fix;// fixed and all functionality is constexpr so You can declare constants see features [1]inlineconstexprfixed_t foo_constant{fixedmath::tan(15 * fixedmath::phi /180)};constexprfixed_tmy_function(fixed_t value)  {usingnamespacefixedmath;return foo_constant +sin(value) / (1.41_fix -2 *cos(value) /4);  }intmain()  {// converting to/from fixed_t// construction from other arithmetic types is explicitfixed_t val1{3.14};fixed_t val2{3u};//- there is no implicit assignment from other typesfloat some_float{3.14f};fixed_t some_fixed;  some_fixed =fixed_t{some_float};//- converting to other arithmetic types coud be done with static cast and is explicitdoublesome_double(some_fixed);// for constant values postfix operator _fix may be used  some_fixed = some_float *2.45_fix;// operation with float is promoted to fixed_t  some_double =4.15 * some_fixed;// operation with double is promoted to double  std::cout << some_double <<"" <<my_function(some_fixed) << std::endl;  }

To execute the unit tests, simply#include <fixedmath/unittests/compile_time_unit_tests.h> in any source file of your project. This enables you to validate the functionality at compile time, ensuring the library's reliability.

Alternatively, unit tests can be executed using CMake/CTest with clang. Runninja test ormake test commands, depending on your build system, as the tests are included in the default CMake configuration of the source folder. To enable or disable this feature, modify theFIXEDMATH_ENABLE_UNIT_TESTS option in theCMakeLists.txt file.

This flexible testing approach ensures that you can easily integrate and verify the functionality of the library within your development workflow.

The development of version 1.0 focused on establishing a robust foundation for fixed-point arithmetic operations, with significant achievements as outlined below:

• Basic arithmetic operations have been successfully implemented.
• Square root calculation using the abacus algorithm and CLZ (Count Leading Zeros), which is supported on x86, ARMv6, and newer, and AArch64 architectures. The approximation error is approximately <= 0.000015.
• Hypotenuse function (hypot) implemented with normalization to prevent overflow and underflow.
• Sine and cosine functions with an error margin of approximately <= 0.0001.
• Tangent function accuracy within |x| <= PI/4 is approximately <= 0.0001. For PI/4 < |x| <= PI/2, the error is <= 0.001, except near 90 degrees where it is <= 0.01.
• Improvements to tangent calculations to limit the domain to |x|<=pi/4.
• Inverse tangent functions (atan,atan2) with an error margin of approximately <= 0.00005.
• Arcsine function (asin) accuracy of approximately <= 0.0001.
• Compatibility with Clang and GCC C++17 compilers confirmed.
• Partial support for MSVC C++17 compiler; refer to "C++ Compilers" notes for details on compiler compatibility.
• Performance comparisons conducted between ARM64 and x86 architectures, demonstrating parity with float/double arithmetic.
• The project is dual-licensed under the MIT License and the Boost Software License, offering flexibility in usage and distribution.

Looking forward, the project aims to expand its offerings and improve in several key areas:

• Expand mathematical functionality based on user needs. If there's something missing that you need, please post an issue to let us know.
• Increase the number of unit tests to cover more scenarios and ensure robustness.
• Pursue further optimizations and enhancements to calculation quality, striving for even higher accuracy and efficiency.

Should you encounter any bugs, we encourage you to file an issue through our issue submissionform. When reporting a bug, please include sufficient information for reproduction, such as astatic_assert(expression), along with the compiler version and target architecture if pertinent. We welcome feature requests and contributions; these can be submitted either as issues or pull requests.

The library is freely available to everyone under the terms of the MIT License or the Boost Software License - Version 1.0. For more details, please refer to the LICENSE.md file.