# Source code for fontTools.misc.fixedTools

    """
    The `OpenType specification <https://docs.microsoft.com/en-us/typography/opentype/spec/otff#data-types>`_
    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.

    .. data:: MAX_F2DOT14

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

    from .roundTools import otRound, nearestMultipleShortestRepr
    import logging

    log = logging.getLogger(__name__)

    __all__ = [
        "MAX_F2DOT14",
        "fixedToFloat",
        "floatToFixed",
        "floatToFixedToFloat",
        "floatToFixedToStr",
        "fixedToStr",
        "strToFixed",
        "strToFixedToFloat",
        "ensureVersionIsLong",
        "versionToFixed",
    ]

    MAX_F2DOT14 = 0x7FFF / (1 << 14)

    def fixedToFloat(value: float, precisionBits: int) -> float:
        """Converts a fixed-point number to a float given the number of
        precision bits.

        Args:
                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
        """
        return value / (1 << precisionBits)

    def floatToFixed(value, precisionBits):
        """Converts a float to a fixed-point number given the number of
        precision bits.

        Args:
                value (float): Floating point value.
                precisionBits (int): Number of precision bits.

        Returns:
                int: Fixed-point representation.

        Examples::

                >>> floatToFixed(-0.61883544921875, precisionBits=14)
                -10139
                >>> floatToFixed(-0.61884, precisionBits=14)
                -10139
        """
        return otRound(value * (1 << precisionBits))

    def 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))``.

        Args:
                value (float): The input floating point value.
                precisionBits (int): Number of precision bits.

        Returns:
                float: The transformed and rounded value.

        Examples::
                >>> import math
                >>> f1 = -0.61884
                >>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14)
                >>> f1 != f2
                True
                >>> math.isclose(f2, -0.61883544921875)
                True
        """
        scale = 1 << precisionBits
        return otRound(value * scale) / scale

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

        Args:
                value (int): The fixed-point value to convert.
                precisionBits (int): Number of precision bits, *up to a maximum of 16*.

        Returns:
                str: A string representation of the value.
        """
        scale = 1 << precisionBits
        return nearestMultipleShortestRepr(value / scale, factor=1.0 / scale)

    def strToFixed(string, precisionBits):
        """Converts a string representing a decimal float to a fixed-point number.

        Args:
                string (str): A string representing a decimal float.
                precisionBits (int): Number of precision bits, *up to a maximum of 16*.

        Returns:
                int: Fixed-point representation.

        Examples::

                >>> ## to convert a float string to a 2.14 fixed-point number:
                >>> strToFixed('-0.61884', precisionBits=14)
                -10139
        """
        value = float(string)
        return otRound(value * (1 << precisionBits))

    def 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))).

        Args:
                string (str): A string representing a decimal float.
                precisionBits (int): Number of precision bits.

        Returns:
                float: The transformed and rounded value.

        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
        """
        value = float(string)
        scale = 1 << precisionBits
        return otRound(value * scale) / scale

    def 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'

        Args:
                value (float): The float value to convert.
                precisionBits (int): Number of precision bits, *up to a maximum of 16*.

        Returns:
                str: A string representation of the value.

        """
        scale = 1 << precisionBits
        return nearestMultipleShortestRepr(value, factor=1.0 / scale)

    def 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 :func:`floatToFixed` if so.

        Args:
                value (Number): a candidate table version number.

        Returns:
                int: A table version number, possibly corrected to fixed-point.
        """
        if value < 0x10000:
            newValue = floatToFixed(value, 16)
            log.warning(
                "Table version value is a float: %.4f; " "fix to use hex instead: 0x%08x",
                value,
                newValue,
            )
            value = newValue
        return value

    def versionToFixed(value):
        """Ensure a table version number is fixed-point.

        Args:
                value (str): a candidate table version number.

        Returns:
                int: A table version number, possibly corrected to fixed-point.
        """
        value = int(value, 0) if value.startswith("0") else float(value)
        value = ensureVersionIsLong(value)
        return value