FixedPoints

A portable fixed point arithmetic library.

Some knowledge of how fixed point types are formatted is required to used this library to full effect. No knowledge of how these operations are implemented is required to use them.

This library was written with Arduino in mind, as well as CPUs with limited floating point support. However, given the templated nature of the library, it should still function on a wide variety of CPUs.

Project Showcase

Here's a list of projects that use FixedPoints:

• 1943 for the Arduboy by @filmote
• XOD Powered Rechargeable Solar Lamp by Victorian DeLorean

If you have a project that uses FixedPoints and would like your work to be showcased here, please raise an issue.

Requirements:

• The Compiler must be C++11 compliant.
• The user should ideally be familar with the Q number format for fixed points.

Licence

This code uses the Apache 2.0 Licence. This means:

• This code comes with no warranty.
• The licensor and any contributors cannot be held liable for damages.
• If you use this code, edited or unedited, you must:
  • Package a copy of LICENCE with your code.
  • Package a copy of NOTICE with your code.
• You may modify the source code.
  • If you modify a file, you must state this prominently in the file (i.e. in a comment at the top).
  • Any modified code may use a different licence.
  • Any unmodified code must carry the same Apache 2.0 licence.
• You may not use any trademarks owned by the licensor.

Conditional Compilation

These are symbols you can define prior to library inclusion to alter the behaviour of the library.

• FIXED_POINTS_USE_NAMESPACE: Define this to wrap all classes and functions in the namespace FixedPoints. Useful for preventing naming conflicts.
• FIXED_POINTS_NO_RANDOM: Define this to disable the random utility functions. Useful for systems that don't have access to long random(void) from avr-libc.

FAQ

• Why can't I multiply UQ32x32 or SQ31x32 by another type?
  • Because it would require a 128-bit integer type to provide enough precision for accurate multiplication.

Contents

This library supplies two core types and sixteen type aliases.

Defines

• FIXED_POINTS_NAMESPACE: The namespace used by FixedPoints. This is empty unless FIXED_POINTS_USE_NAMESPACE is defined prior to inclusion.
• FIXED_POINTS_DETAILS: An infrastructure macro that should not be used in user code. It is safe to undefine this if it is causing problems.
• FIXED_POINTS_BEGIN_NAMESPACE: An infrastructure macro that should not be used in user code. It is safe to undefine this if it is causing problems.
• FIXED_POINTS_END_NAMESPACE: An infrastructure macro that should not be used in user code. It is safe to undefine this if it is causing problems.

Core Types:

The core types are provided by FixedPoints.h.

• UFixed<I, F>: An unsigned fixed point type where I is the number of bits used for the integer part of the number and F is the number of bits used for the fractional part of the number.
• SFixed<I, F>: An signed fixed point type where I is the number of bits used for the integer part of the number (excluding the implicit sign bit) and F is the number of bits used for the fractional part of the number.

Aliases:

The common aliases are provided by FixedPointsCommon.h.

• UQ4x4: An alias for UFixed<4, 4>, an 8-bit unsigned fixed point in the Q4.4 format.
• UQ8x8: An alias for UFixed<8, 8>, a 16-bit unsigned fixed point in the Q8.8 format.
• UQ16x16: An alias for UFixed<16, 16>, a 32-bit unsigned fixed point in the Q16.16 format.
• UQ32x32: An alias for UFixed<32, 32>, a 64-bit unsigned fixed point in the Q32.32 format.
• UQ1x7: An alias for UFixed<1, 7>, an 8-bit unsigned fixed point in the Q1.7 format.
• UQ1x15: An alias for UFixed<1, 15>, a 16-bit unsigned fixed point in the Q1.15 format.
• UQ1x31: An alias for UFixed<1, 31>, a 32-bit unsigned fixed point in the Q1.31 format.
• UQ1x63: An alias for UFixed<1, 63>, a 64-bit unsigned fixed point in the Q1.63 format.
• SQ3x4: An alias for SFixed<3, 4>, an 8-bit signed fixed point in the Q3.4 format with implicit sign bit.
• SQ7x8: An alias for SFixed<7, 8>, a 16-bit signed fixed point in the Q7.8 format with implicit sign bit.
• SQ15x16: An alias for SFixed<15, 16>, a 32-bit signed fixed point in the Q15.16 format with implicit sign bit.
• SQ31x32: An alias for SFixed<31, 32>, a 64-bit signed fixed point in the Q31.32 format with implicit sign bit.
• SQ1x6: An alias for SFixed<1, 6>, an 8-bit signed fixed point in the Q1.6 format with implicit sign bit.
• SQ1x14: An alias for SFixed<1, 14>, a 16-bit signed fixed point in the Q1.14 format with implicit sign bit.
• SQ1x30: An alias for SFixed<1, 30>, a 32-bit signed fixed point in the Q1.30 format with implicit sign bit.
• SQ1x62: An alias for SFixed<1, 62>, a 64-bit signed fixed point in the Q1.62 format with implicit sign bit.

(About Q Format.)

Operators:

• +: Adds two UFixeds or two SFixeds
• -: Subtracts two UFixeds or two SFixeds
• *: Multiplies two UFixeds or two SFixeds
• /: Divides two UFixeds or two SFixeds
• ==: Compares two UFixeds or two SFixeds
• !=: Compares two UFixeds or two SFixeds
• <: Compares two UFixeds or two SFixeds
• <=: Compares two UFixeds or two SFixeds
• >: Compares two UFixeds or two SFixeds
• >=: Compares two UFixeds or two SFixeds

Free Functions:

• floorFixed: The floor operation.
• ceilFixed: The Ceiling operation
• roundFixed: Rounding operation.
• truncFixed: Truncation operation.
• signbitFixed: Returns true for signed numbers and false for unsigned numbers.
• copysignFixed: Returns a value with the magnitude of the first argument and the sign of the second argument.
• multiply: Multiplies two UFixeds or two SFixeds, returns a result that is twice the resolution of the input.

Member Functions:

• UFixed<I, F>::getInteger: Gets the integer part of an unsigned fixed point.

• UFixed<I, F>::getFraction: Gets the fractional part of an unsigned fixed point.

• UFixed<I, F>::getInternal: Gets the internal representation of an unsigned fixed point.

• SFixed<I, F>::getInteger: Gets the integer part of a signed fixed point.

• SFixed<I, F>::getFraction: Gets the fractional part of a signed fixed point.

• SFixed<I, F>::getInternal: Gets the internal representation of a signed fixed point.

Static Functions:

• UFixed<I, F>::fromInternal: Produces an unsigned fixed point number from its internal representation.
• SFixed<I, F>::fromInternal: Produces a signed fixed point number from its internal representation.

Construction:

Note that both UFixed<I, F> and SFixed<I, F> are implicitly compile-time constructable from all integer and decimal literals. This means that you may write code such as UFixed<8, 8> value = 0.5; without incurring a runtime cost for converting from double to UFixed<8, 8> because the constructor is constexpr.

UFixed<I, F> is constructable from:

• Any integer literal type, regardless of sign. -- This constructs the fixed point as an integer with no fractional part. -- A value that does not fit shall be truncated without warning. -- If a constant value is used, the fixed point shall be constructed at compile time.
• An unsigned integer part and an unsigned fractional part. -- The integer part is of the smallest type capable of representing I bits. -- The fractional part is of the smallest type capable of representing F bits. -- If constant values are used, the fixed point shall be constructed at compile time.
• Any decimal literal type, regardless of sign. -- This constructs the fixed point as a best approximation of the provided value. -- A value that does not fit shall be truncated without warning. -- If a constant value is used, the fixed point shall be constructed at compile time.

SFixed<I, F> is constructable from:

• Any integer literal type, regardless of sign. -- This constructs the fixed point as an integer with no fractional part. -- A value that does not fit shall be truncated without warning. -- If a constant value is used, the fixed point shall be constructed at compile time.
• A signed integer part and an unsigned fractional part. -- The integer part is of the smallest type capable of representing I + 1 bits. -- The fractional part is of the smallest type capable of representing F bits. -- If constant values are used, the fixed point shall be constructed at compile time.
• Any decimal literal type, regardless of sign. -- This constructs the fixed point as a best approximation of the provided value. -- A value that does not fit shall be truncated without warning. -- If a constant value is used, the fixed point shall be constructed at compile time.

Casts:

UFixed<I, F> is explicitly convertible to:

• float.
• double.
• The smallest unsigned type capable of holding its integer part. I.e. a type of at least I bits.
• Another UFixed type of a different scale. E.g. UFixed<4, 4> may be converted to UFixed<8, 8> and vice versa.

SFixed<I, F> is explicitly convertible to:

• float.
• double.
• The smallest signed type capable of holding its integer part. I.e. a type of at least I + 1 bits.
• Another SFixed type of a different scale. E.g. SFixed<3, 4> may be converted to SFixed<7, 8> and vice versa.