[mypyc] Update float documentation

Floats are now unboxed.
python · JukkaL · Mar 22, 2023 · Mar 19, 2023 · Mar 19, 2023 · Mar 19, 2023
commit 1d46ba73be9722e3ec911be00ff21adf3d0f83bf
diff --git a/mypyc/doc/float_operations.rst b/mypyc/doc/float_operations.rst
@@ -7,18 +7,37 @@ These ``float`` operations have fast, optimized implementations. Other
 floating point operations use generic implementations that are often
 slower.
 
-.. note::
-
-   At the moment, only a few float operations are optimized. This will
-   improve in future mypyc releases.
-
 Construction
 ------------
 
 * Float literal
+* ``float(integer)``
 * ``float(string)``
 
+Operators
+---------
+
+* Arithmetic (``+``, ``-``, ``*``, ``/``, ``//``, ``%``)
+* Comparisons (``==``, ``!=``, ``<``, etc.)
+* Augmented assignment (``x += y``, etc.)
+
 Functions
 ---------
 
+* ``int(f)``
+* ``i32(f)``
+* ``i64(f)``
 * ``abs(f)``
+* ``math.sin(f)``
+* ``math.cos(f)``
+* ``math.tan(f)``
+* ``math.sqrt(f)``
+* ``math.exp(f)``
+* ``math.log(f)``
+* ``math.floor(f)``
+* ``math.ceil(f)``
+* ``math.fabs(f)``
+* ``math.pow(x, y)``
+* ``math.copysign(x, y)``
+* ``math.isinf(f)``
+* ``math.isnan(f)``
diff --git a/mypyc/doc/int_operations.rst b/mypyc/doc/int_operations.rst
@@ -19,7 +19,7 @@ Construction
 Operators
 ---------
 
-* Arithmetic (``+``, ``-``, ``*``, ``//``, ``%``)
+* Arithmetic (``+``, ``-``, ``*``, ``//``, ``/``, ``%``)
 * Bitwise operations (``&``, ``|``, ``^``, ``<<``, ``>>``, ``~``)
 * Comparisons (``==``, ``!=``, ``<``, etc.)
 * Augmented assignment (``x += y``, etc.)

diff --git a/mypyc/doc/performance_tips_and_tricks.rst b/mypyc/doc/performance_tips_and_tricks.rst
@@ -103,8 +103,6 @@ These things also tend to be relatively slow:
 
 * Using generator functions
 
-* Using floating point numbers (they are relatively unoptimized)
-
 * Using callable values (i.e. not leveraging early binding to call
   functions or methods)
 
@@ -160,6 +158,8 @@ Here are examples of features that are fast, in no particular order
 
 * Many integer operations
 
+* Many ``float`` operations
+
 * Booleans
 
 * :ref:`Native list operations <list-ops>`, such as indexing,

diff --git a/mypyc/doc/using_type_annotations.rst b/mypyc/doc/using_type_annotations.rst
@@ -271,7 +271,8 @@ Value and heap types
 In CPython, memory for all objects is dynamically allocated on the
 heap. All Python types are thus *heap types*. In compiled code, some
 types are *value types* -- no object is (necessarily) allocated on the
-heap.  ``bool``, ``None`` and fixed-length tuples are value types.
+heap.  ``bool``, ``float``, ``None`` and fixed-length tuples are value
+types.
 
 ``int`` is a hybrid. For typical integer values, it is a value
 type. Large enough integer values, those that require more than 63
@@ -287,9 +288,9 @@ Value types have a few differences from heap types:
 * Similarly, mypyc transparently changes from a heap-based
   representation to a value representation (unboxing).
 
-* Object identity of integers and tuples is not preserved. You should
-  use ``==`` instead of ``is`` if you are comparing two integers or
-  fixed-length tuples.
+* Object identity of integers, floating point values and tuples is not
+  preserved. You should use ``==`` instead of ``is`` if you are comparing
+  two integers, floats or fixed-length tuples.
 
 * When an instance of a subclass of a value type is converted to the
   base type, it is implicitly converted to an instance of the target
@@ -312,3 +313,24 @@ Example::
         x = a[0]
         # True is converted to 1 on assignment
         x = True
+
+Since integers and floating point values have a different runtime
+representations and neither can represent all the values of the other
+type, type narrowing of floating point values through assignment is
+disallowed in compiled code. For consistency, mypyc rejects assigning
+an integer value to a float variable even in variable initialization.
+An explicit conversion is required.
+
+Examples::
+
+    def narrowing(n: int) -> None:
+        # Error: Incompatible value representations in assignment
+        # (expression has type "int", variable has type "float")
+        x: float = 0
+
+        y: float = 0.0  # Ok
+
+        if f():
+            y = n  # Error
+        if f():
+            y = float(n)  # Ok