1"""
2The `OpenType specification <https://docs.microsoft.com/en-us/typography/opentype/spec/otff#data-types>`_
3defines two fixed-point data types:
4
5``Fixed``
6	A 32-bit signed fixed-point number with a 16 bit twos-complement
7	magnitude component and 16 fractional bits.
8``F2DOT14``
9	A 16-bit signed fixed-point number with a 2 bit twos-complement
10	magnitude component and 14 fractional bits.
11
12To support reading and writing data with these data types, this module provides
13functions for converting between fixed-point, float and string representations.
14
15.. data:: MAX_F2DOT14
16
17	The maximum value that can still fit in an F2Dot14. (1.99993896484375)
18"""
19
20from .roundTools import otRound
21import logging
22
23log = logging.getLogger(__name__)
24
25__all__ = [
26	"MAX_F2DOT14",
27	"fixedToFloat",
28	"floatToFixed",
29	"floatToFixedToFloat",
30	"floatToFixedToStr",
31	"fixedToStr",
32	"strToFixed",
33	"strToFixedToFloat",
34	"ensureVersionIsLong",
35	"versionToFixed",
36]
37
38
39MAX_F2DOT14 = 0x7FFF / (1 << 14)
40
41
42def fixedToFloat(value, precisionBits):
43	"""Converts a fixed-point number to a float given the number of
44	precision bits.
45
46	Args:
47		value (int): Number in fixed-point format.
48		precisionBits (int): Number of precision bits.
49
50	Returns:
51		Floating point value.
52
53	Examples::
54
55		>>> import math
56		>>> f = fixedToFloat(-10139, precisionBits=14)
57		>>> math.isclose(f, -0.61883544921875)
58		True
59	"""
60	return value / (1 << precisionBits)
61
62
63def floatToFixed(value, precisionBits):
64	"""Converts a float to a fixed-point number given the number of
65	precision bits.
66
67	Args:
68		value (float): Floating point value.
69		precisionBits (int): Number of precision bits.
70
71	Returns:
72		int: Fixed-point representation.
73
74	Examples::
75
76		>>> floatToFixed(-0.61883544921875, precisionBits=14)
77		-10139
78		>>> floatToFixed(-0.61884, precisionBits=14)
79		-10139
80	"""
81	return otRound(value * (1 << precisionBits))
82
83
84def floatToFixedToFloat(value, precisionBits):
85	"""Converts a float to a fixed-point number and back again.
86
87	By converting the float to fixed, rounding it, and converting it back
88	to float again, this returns a floating point values which is exactly
89	representable in fixed-point format.
90
91	Note: this **is** equivalent to ``fixedToFloat(floatToFixed(value))``.
92
93	Args:
94		value (float): The input floating point value.
95		precisionBits (int): Number of precision bits.
96
97	Returns:
98		float: The transformed and rounded value.
99
100	Examples::
101		>>> import math
102		>>> f1 = -0.61884
103		>>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14)
104		>>> f1 != f2
105		True
106		>>> math.isclose(f2, -0.61883544921875)
107		True
108	"""
109	scale = 1 << precisionBits
110	return otRound(value * scale) / scale
111
112
113def fixedToStr(value, precisionBits):
114	"""Converts a fixed-point number to a string representing a decimal float.
115
116	This chooses the float that has the shortest decimal representation (the least
117	number of fractional decimal digits).
118
119	For example, to convert a fixed-point number in a 2.14 format, use
120	``precisionBits=14``::
121
122		>>> fixedToStr(-10139, precisionBits=14)
123		'-0.61884'
124
125	This is pretty slow compared to the simple division used in ``fixedToFloat``.
126	Use sporadically when you need to serialize or print the fixed-point number in
127	a human-readable form.
128
129	Args:
130		value (int): The fixed-point value to convert.
131		precisionBits (int): Number of precision bits, *up to a maximum of 16*.
132
133	Returns:
134		str: A string representation of the value.
135	"""
136	if not value: return "0.0"
137
138	scale = 1 << precisionBits
139	value /= scale
140	eps = .5 / scale
141	lo = value - eps
142	hi = value + eps
143	# If the range of valid choices spans an integer, return the integer.
144	if int(lo) != int(hi):
145		return str(float(round(value)))
146	fmt = "%.8f"
147	lo = fmt % lo
148	hi = fmt % hi
149	assert len(lo) == len(hi) and lo != hi
150	for i in range(len(lo)):
151		if lo[i] != hi[i]:
152			break
153	period = lo.find('.')
154	assert period < i
155	fmt = "%%.%df" % (i - period)
156	return fmt % value
157
158
159def strToFixed(string, precisionBits):
160	"""Converts a string representing a decimal float to a fixed-point number.
161
162	Args:
163		string (str): A string representing a decimal float.
164		precisionBits (int): Number of precision bits, *up to a maximum of 16*.
165
166	Returns:
167		int: Fixed-point representation.
168
169	Examples::
170
171	>>> ## to convert a float string to a 2.14 fixed-point number:
172	>>> strToFixed('-0.61884', precisionBits=14)
173	-10139
174	"""
175	value = float(string)
176	return otRound(value * (1 << precisionBits))
177
178
179def strToFixedToFloat(string, precisionBits):
180	"""Convert a string to a decimal float with fixed-point rounding.
181
182	This first converts string to a float, then turns it into a fixed-point
183	number with ``precisionBits`` fractional binary digits, then back to a
184	float again.
185
186	This is simply a shorthand for fixedToFloat(floatToFixed(float(s))).
187
188	Args:
189		string (str): A string representing a decimal float.
190		precisionBits (int): Number of precision bits.
191
192	Returns:
193		float: The transformed and rounded value.
194
195	Examples::
196
197		>>> import math
198		>>> s = '-0.61884'
199		>>> bits = 14
200		>>> f = strToFixedToFloat(s, precisionBits=bits)
201		>>> math.isclose(f, -0.61883544921875)
202		True
203		>>> f == fixedToFloat(floatToFixed(float(s), precisionBits=bits), precisionBits=bits)
204		True
205	"""
206	value = float(string)
207	scale = 1 << precisionBits
208	return otRound(value * scale) / scale
209
210
211def floatToFixedToStr(value, precisionBits):
212	"""Convert float to string with fixed-point rounding.
213
214	This uses the shortest decimal representation (ie. the least
215	number of fractional decimal digits) to represent the equivalent
216	fixed-point number with ``precisionBits`` fractional binary digits.
217	It uses fixedToStr under the hood.
218
219	>>> floatToFixedToStr(-0.61883544921875, precisionBits=14)
220	'-0.61884'
221
222	Args:
223		value (float): The float value to convert.
224		precisionBits (int): Number of precision bits, *up to a maximum of 16*.
225
226	Returns:
227		str: A string representation of the value.
228
229	"""
230	fixed = otRound(value * (1 << precisionBits))
231	return fixedToStr(fixed, precisionBits)
232
233
234def ensureVersionIsLong(value):
235	"""Ensure a table version is an unsigned long.
236
237	OpenType table version numbers are expressed as a single unsigned long
238	comprising of an unsigned short major version and unsigned short minor
239	version. This function detects if the value to be used as a version number
240	looks too small (i.e. is less than ``0x10000``), and converts it to
241	fixed-point using :func:`floatToFixed` if so.
242
243	Args:
244		value (Number): a candidate table version number.
245
246	Returns:
247		int: A table version number, possibly corrected to fixed-point.
248	"""
249	if value < 0x10000:
250		newValue = floatToFixed(value, 16)
251		log.warning(
252			"Table version value is a float: %.4f; "
253			"fix to use hex instead: 0x%08x", value, newValue)
254		value = newValue
255	return value
256
257
258def versionToFixed(value):
259	"""Ensure a table version number is fixed-point.
260
261	Args:
262		value (str): a candidate table version number.
263
264	Returns:
265		int: A table version number, possibly corrected to fixed-point.
266	"""
267	value = int(value, 0) if value.startswith("0") else float(value)
268	value = ensureVersionIsLong(value)
269	return value
270