Repository files navigation

The Compositional Numeric Library (CNL) is a C++ library of fixed-precisionnumeric classes which enhance integers to deliver safer, simpler, cheaperarithmetic types. Documentation can be foundhere.You can try out CNL on Compiler Explorerhere.

CNL is particularly well-suited to:

• compute or energy-constrained environments where FPUs are absent or costly;
• compute or energy-intensive environments where arithmetic is the bottlenecksuch as simulations, machine learning applications and DSPs; and
• domains such as finance where precision is essential.

The latest version of CNL requires a C++20-compatible tool chain.(Version 1.x supports C++11.)CNL is continually tested on the following systems:

Tested:

• GCC 10, 11, 12
• Clang 10, 11, 12, 13, 14
• libstdc++ 10, 11, 12
• libc++ 13, 14
• CMake 3.23.1
• Conan 1.48.1

Tested:

• GCC 11 / Clang 13
• CMake 3.23.1
• Conan 1.48.1

Tested:

• Visual Studio 2019 Version 16 (19.29.30145.0)
• Visual Studio 2022 Version 17 (19.32.31329.0)
• CMake 3.23.1
• Conan 1.48.1

CMake scripts are provided.

• To build and install CNL on your system:

mkdir build&&cd buildcmake ..cmake --build. --target install

Note: you may need user privileges to install the library.Alternatively, you can install to user directory usingCMAKE_INSTALL_PREFIX:

mkdir build&&cd buildcmake -DCMAKE_INSTALL_PREFIX:FILE=/home/username/someplace ..cmake --build. --target install

Alternatively, CNL is a header-only library so you can simply point to theinclude directory

c++ -isystem /path/to/cnl/include -std=c++20 my_program.cpp

or even include the root header directly in your code:

#include"/path/to/cnl/include/cnl/all.h"

The test suite uses CMake and depends on Google Test and Google Benchmark.Optional integration tests use Boost.Multiprecision.

1. Conan can be used to pull in essential dependencies.This example assumes GCC but other tool chain files are provided:

   cd buildconan profile new --detect --force defaultconan profile update settings.compiler.libcxx=libstdc++11 default# GCC/Clang onlyconan profile update env.CONAN_CMAKE_TOOLCHAIN_FILE=../test/toolchain/gcc.cmake default# GCC onlyconan install --build=missing --options test=unit ..

   ... and then configure, build and run unit tests:

   conan build --configure --build --test ..

2. To run benchmarks, use--options test=benchmark...

   conan install --build=missing --options test=benchmark ..

   then configure and build

   conan build --configure --build ..

   and finally run explicitly to see the results.

   ./test/benchmark/test-benchmark

The API is exposed through headers in theinclude directory.Add this to your system header list and include, e.g.:

// to use a specific type:#include<cnl/scaled_integer.h>// or to include all CNL types:#include<cnl/all.h>

Examples of projects using CNL:

• CDSP - Compositional DSP Library forC++;
• BrewBlox firmware - firmwarefor a brewery controller
• cnl_example - minimalCMake-based project which uses CNL as a dependency.

• CNLdocumentation
• CppCon 2017presentation
• Embedded Artistryarticle
• ISO C++ papers:
  • P0037 - Fixed-Point Real Numbers
  • P0554 - Composition of Arithmetic Types
  • P0827 - General-Purpose Constant Value Type
  • P0828 - Elastic Integers
  • P1050 - Fractional Numeric Type

• Much of the simplicity and efficiency in CNL's API design can be traced backto Matheus Izvekov'sfp fixed point library.
• Together with Lawrence Crowl's fixed-point paper,P0106,it lays the groundwork for integer-backed real number approximation that minimizesloss of performance and precision.
• fpm is a fixed-point math library with ahigh quantity of mathematical functions.
• Fixed Point Classis a single-header C++98 solution from Peter Schregle's.

All feedback greatly appreciated.

• CNL Issues
• cnl@john.mcfarlane.name