# fixedTools: Tools for working with fixed-point numbers

The OpenType specification defines two fixed-point data types:

`Fixed`

  A 32-bit signed fixed-point number with a 16 bit twos-complement magnitude component and 16 fractional bits.

`F2DOT14`

  A 16-bit signed fixed-point number with a 2 bit twos-complement magnitude component and 14 fractional bits.

To support reading and writing data with these data types, this module provides functions for converting between fixed-point, float and string representations.

fontTools.misc.fixedTools.MAX_F2DOT14

  The maximum value that can still fit in an F2Dot14. (1.99993896484375)

fontTools.misc.fixedTools.ensureVersionIsLong(value)

  Ensure a table version is an unsigned long.

  OpenType table version numbers are expressed as a single unsigned long comprising of an unsigned short major version and unsigned short minor version. This function detects if the value to be used as a version number looks too small (i.e. is less than `0x10000`), and converts it to fixed-point using `floatToFixed()` if so.

  Parameters

    value (Number) – a candidate table version number.

  Returns

    A table version number, possibly corrected to fixed-point.

  Return type

    int

fontTools.misc.fixedTools.fixedToFloat(value, precisionBits)

  Converts a fixed-point number to a float given the number of precision bits.

  Parameters

    - value (int) – Number in fixed-point format.

    - precisionBits (int) – Number of precision bits.

  Returns

    Floating point value.

  Examples:

      >>> import math
      >>> f = fixedToFloat(-10139, precisionBits=14)
      >>> math.isclose(f, -0.61883544921875)
      True

fontTools.misc.fixedTools.fixedToStr(value, precisionBits)

  Converts a fixed-point number to a string representing a decimal float.

  This chooses the float that has the shortest decimal representation (the least number of fractional decimal digits).

  For example, to convert a fixed-point number in a 2.14 format, use `precisionBits=14`:

      >>> fixedToStr(-10139, precisionBits=14)
      '-0.61884'

  This is pretty slow compared to the simple division used in `fixedToFloat`. Use sporadically when you need to serialize or print the fixed-point number in a human-readable form. It uses nearestMultipleShortestRepr under the hood.

  Parameters

    - value (int) – The fixed-point value to convert.

    - precisionBits (int) – Number of precision bits, up to a maximum of 16.

  Returns

    A string representation of the value.

  Return type

    str

fontTools.misc.fixedTools.floatToFixed(value, precisionBits)

  Converts a float to a fixed-point number given the number of precision bits.

  Parameters

    - value (float) – Floating point value.

    - precisionBits (int) – Number of precision bits.

  Returns

    Fixed-point representation.

  Return type

    int

  Examples:

      >>> floatToFixed(-0.61883544921875, precisionBits=14)
      -10139
      >>> floatToFixed(-0.61884, precisionBits=14)
      -10139

fontTools.misc.fixedTools.floatToFixedToFloat(value, precisionBits)

  Converts a float to a fixed-point number and back again.

  By converting the float to fixed, rounding it, and converting it back to float again, this returns a floating point values which is exactly representable in fixed-point format.

  Note: this is equivalent to `fixedToFloat(floatToFixed(value))`.

  Parameters

    - value (float) – The input floating point value.

    - precisionBits (int) – Number of precision bits.

  Returns

    The transformed and rounded value.

  Return type

    float

  Examples::

        >>> import math
        >>> f1 = -0.61884
        >>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14)
        >>> f1 != f2
        True
        >>> math.isclose(f2, -0.61883544921875)
        True

fontTools.misc.fixedTools.floatToFixedToStr(value, precisionBits)

  Convert float to string with fixed-point rounding.

  This uses the shortest decimal representation (ie. the least number of fractional decimal digits) to represent the equivalent fixed-point number with `precisionBits` fractional binary digits. It uses nearestMultipleShortestRepr under the hood.

      >>> floatToFixedToStr(-0.61883544921875, precisionBits=14)
      '-0.61884'

  Parameters

    - value (float) – The float value to convert.

    - precisionBits (int) – Number of precision bits, up to a maximum of 16.

  Returns

    A string representation of the value.

  Return type

    str

fontTools.misc.fixedTools.strToFixed(string, precisionBits)

  Converts a string representing a decimal float to a fixed-point number.

  Parameters

    - string (str) – A string representing a decimal float.

    - precisionBits (int) – Number of precision bits, up to a maximum of 16.

  Returns

    Fixed-point representation.

  Return type

    int

  Examples:

      >>> ## to convert a float string to a 2.14 fixed-point number:
      >>> strToFixed('-0.61884', precisionBits=14)
      -10139

fontTools.misc.fixedTools.strToFixedToFloat(string, precisionBits)

  Convert a string to a decimal float with fixed-point rounding.

  This first converts string to a float, then turns it into a fixed-point number with `precisionBits` fractional binary digits, then back to a float again.

  This is simply a shorthand for fixedToFloat(floatToFixed(float(s))).

  Parameters

    - string (str) – A string representing a decimal float.

    - precisionBits (int) – Number of precision bits.

  Returns

    The transformed and rounded value.

  Return type

    float

  Examples:

      >>> import math
      >>> s = '-0.61884'
      >>> bits = 14
      >>> f = strToFixedToFloat(s, precisionBits=bits)
      >>> math.isclose(f, -0.61883544921875)
      True
      >>> f == fixedToFloat(floatToFixed(float(s), precisionBits=bits), precisionBits=bits)
      True

fontTools.misc.fixedTools.versionToFixed(value)

  Ensure a table version number is fixed-point.

  Parameters

    value (str) – a candidate table version number.

  Returns

    A table version number, possibly corrected to fixed-point.

  Return type

    int