View on GitHub

FPM

C++ header-only fixed-point math library

fpm

A C++ header-only fixed-point math library. “fpm” stands for “fixed-point math”.

It is designed to serve as a drop-in replacement for floating-point types and aims to provide as much of the standard library’s functionality as possible with exclusively integers. fpm requires C++11 or higher.

Usage

fpm defines the fpm::fixed class, which is templated on the underlying integer type and the number of bits in the fraction:

namespace fpm {
    template <typename BaseType, typename IntermediateType, unsigned int FractionBits>
    class fixed;
}

Note: It’s recommended to use a signed integer type for BaseType (and IntermediateType) to emulate floating-point numbers and to allow the compiler to optimize the computations, since overflow and underflow are undefined for signed integer types.

To use this class, simply include its header:

#include <fpm/fixed.hpp>

You may wish to typedef a particular choice of underlying type, intermediate type and fraction bitcount, e.g.:

using position = fpm::fixed<std::int32_t, std::int64_t, 16>;

This defines a signed 16.16 fixed-point number with a range of -32768 to 32767.999985… and a resolution of 0.0000153… It uses 64-bit integers as intermediate type during calculations to avoid loss of information.

For your convenience, several popular fixed-point formats have been defined in the fpm namespace:

namespace fpm {
    using fixed_16_16 = fixed<std::int32_t, std::int64_t, 16>;  // Q16.16 format
    using fixed_24_8  = fixed<std::int32_t, std::int64_t, 8>;   // Q24.8 format
    using fixed_8_24  = fixed<std::int32_t, std::int64_t, 24>;  // Q8.24 format
}

Mathematical functions

FPM offers the header <fpm/math.hpp> with mathematical functions that operate on its fixed-point types, similar to <math.hpp> for floating-point types. The available functions for fixed-point types include:

Notes:

Specialized customization points

The header <fpm/fixed.hpp> provides specializations for fpm::fixed for the following types:

Conversions

The intent behind fpm is to replace floats for purposes of performance or portability. Thus, it guards against accidental usage of floats by requiring explicit conversion:

fpm::fixed_16_16 a = 0.5;        // Error: implicit construction from float
fpm::fixed_16_16 b { 0.5 };      // OK: explicit construction from float
fpm::fixed_16_16 c = b * 0.5;    // Error: implicit conversion from float
float d = b;                     // Error: implicit conversion to float
float e = static_cast<float>(b); // OK: explicit conversion to float

For integers, this still applies to initialization, but arithmetic operations can use integers:

fpm::fixed_16_16 a = 2;        // Error: implicit construction from int
fpm::fixed_16_16 b { 2 };      // OK: explicit construction from int
fpm::fixed_16_16 c = b / 2;    // OK
int d = b;                     // Error: requires explicit conversion
int e = static_cast<int>(b);   // OK: explicit conversion to int

You must still guard against underflow and overflow, though.

fpm::fixed<A, B, C> can be constructed from an fpm::fixed<D, E, F> via explicit construction. This allows for conversion between fixed-point numbers of differing precision and range. Depending on the respective underlying types and number of fraction bits, this conversion may throw away high bits in the integral or low bits in the fraction.

Printing and reading fixed-point numbers

The <fpm/ios.hpp> header provides streaming operators. Simply stream an expression of type fpm::fixed to or from a std::ostream.

For instance, the following program prints "===3.142e+02":

#include <fpm/fixed.hpp>
#include <fpm/ios.hpp>
#include <iostream>
#include <iomanip>

int main() {
    fpm::fixed_16_16 x { 314.1516 };
    std::cout << std::setw(12) << std::setfill('=') << std::setprecision(3) << std::scientific << x << std::endl;
    return 0;
}

Reading fixed point numbers works similarly, by streaming fpm::fixed types from a std::istream.

fpm’s implementation of the streaming operators emulates streaming native floats as closely as possible without using floating-point types.

Common constants

The following static member functions in the fpm::fixed class provide common mathematical constants in the fixed type:

Accuracy and performance

Please refer to the pages for accuracy and performance results.

Limitations

Unlike floating-point numbers, fpm::fixed:

Notably the last point requires careful use of fixed-point numbers: like integers, you must ensure that they do not overflow or underflow.

Alternatives