Repository files navigation

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.

Here's a list of projects that useFixedPoints:

• 1943 for theArduboy by@filmote
• XOD Powered Rechargeable Solar Lamp byVictorian DeLorean
• Pod Manager for theArduboy by@felipemanga

If you have a project that usesFixedPoints and would like your work to be showcased here,pleaseraise an issue.

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

This code uses the Apache 2.0 Licence.This means:

• This code comes withno warranty.
  • The licensor and any contributorscannot be held liable for damages.
• If you use this code, modified or unmodified:
  • Youmust package a copy of LICENCE with your code.
  • Youmust package a copy of NOTICE with your code.
  • You are not required to distribute the source code.
• Youmust not use any trademarks owned by the licensor.
  • Unless you have specific permission to do so.
• Youmay modify the source code.
  • If you modify the code, youmust state this fact prominently within the source file.
    • E.g. in a comment at the top of the source file.
  • You are under no obligation to distribute the source code of your modifications.
• You may incorporate any part of the code into another project.
  • That projectmay use a different licence.
  • That codemust retain the Apache 2.0 licence notice, including the copyright notice.
  • If the code is modified, the modificationsmay be published under a different licence.
    • The Apache 2.0 licence still applies to unmodified portions.
    • The copyright and licence notices for the unmodified portionsmust still be prominently displayed.
    • It is advised that you do not do this, as it is highly unusual and untested in court.

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 namespaceFixedPoints. 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 tolong random(void) from avr-libc.

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

This library supplies two core types and sixteen type aliases.

• FIXED_POINTS_NAMESPACE: The namespace used by FixedPoints. This is empty unlessFIXED_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.

The core types are provided byFixedPoints.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.

The common aliases are provided byFixedPointsCommon.h.

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

(About Q Format.)

• +: Adds twoUFixeds or twoSFixeds
• -: Subtracts twoUFixeds or twoSFixeds
• *: Multiplies twoUFixeds or twoSFixeds
• /: Divides twoUFixeds or twoSFixeds
• ==: Compares twoUFixeds or twoSFixeds
• !=: Compares twoUFixeds or twoSFixeds
• <: Compares twoUFixeds or twoSFixeds
• <=: Compares twoUFixeds or twoSFixeds
• >: Compares twoUFixeds or twoSFixeds
• >=: Compares twoUFixeds or twoSFixeds

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

• 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.

• 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.

Note that bothUFixed<I, F> andSFixed<I, F> are implicitly compile-time constructable from all integer and decimal literals.This means that you may write code such asUFixed<8, 8> value = 0.5; without incurring a runtime cost for converting fromdouble toUFixed<8, 8> because the constructor isconstexpr.

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 representingI bits.-- The fractional part is of the smallest type capable of representingF 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 representingI + 1 bits.-- The fractional part is of the smallest type capable of representingF 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.

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 leastI bits.
• AnotherUFixed type of a different scale. E.g.UFixed<4, 4> may be converted toUFixed<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 leastI + 1 bits.
• AnotherSFixed type of a different scale. E.g.SFixed<3, 4> may be converted toSFixed<7, 8> and vice versa.