gh-121249: Support _Complex types in the struct module

python · vstinner · Oct 7, 2024 · Jun 30, 2024 · Jul 11, 2024 · Jul 13, 2024
commit c60f4a404b43e835f85c8ed7e51f63f1d9f36bf5
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
@@ -267,12 +267,26 @@ platform-dependent.
 | ``P``  | :c:expr:`void \*`        | integer            |                | \(5)       |
 +--------+--------------------------+--------------------+----------------+------------+

+Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is
+supported, the following format characters are available:
+
+--------+--------------------------+--------------------+----------------+------------+
+| Format | C Type                   | Python type        | Standard size  | Notes      |
+========+==========================+====================+================+============+
+| ``E``  | :c:expr:`float complex`  | complex            | 8              | \(10)      |
+--------+--------------------------+--------------------+----------------+------------+
+| ``C``  | :c:expr:`double complex` | complex            | 16             | \(10)      |
+--------+--------------------------+--------------------+----------------+------------+
+
 .. versionchanged:: 3.3
   Added support for the ``'n'`` and ``'N'`` formats.

 .. versionchanged:: 3.6
   Added support for the ``'e'`` format.

+.. versionchanged:: 3.14
+   Added support for ``'E'`` and ``'C'`` formats.
+

 Notes:

@@ -349,6 +363,11 @@ Notes:
   of bytes.  As a special case, ``'0s'`` means a single, empty string (while
   ``'0c'`` means 0 characters).

+(10)
+   For the ``'E'`` and ``'C'`` conversion codes, the packed representation uses
+   the IEEE 754 binary32 and binary64 format for components of the complex
+   number, regardless of the floating-point format used by the platform.
+
 A format character may be preceded by an integral repeat count.  For example,
 the format string ``'4h'`` means exactly the same as ``'hhhh'``.


diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
@@ -208,8 +208,10 @@ class c_longdouble(_SimpleCData):
 try:
    class c_double_complex(_SimpleCData):
        _type_ = "C"
+    _check_size(c_double_complex)
    class c_float_complex(_SimpleCData):
        _type_ = "E"
+    _check_size(c_float_complex)
    class c_longdouble_complex(_SimpleCData):
        _type_ = "F"
 except AttributeError:

diff --git a/Lib/test/test_struct.py b/Lib/test/test_struct.py
@@ -1,4 +1,5 @@
 from collections import abc
+from itertools import combinations
 import array
 import gc
 import math
@@ -17,6 +18,15 @@
 integer_codes = 'b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q', 'n', 'N'
 byteorders = '', '@', '=', '<', '>', '!'

+INF = float('inf')
+NAN = float('nan')
+
+try:
+    struct.pack('C', 1j)
+    have_c_complex = True
+except struct.error:
+    have_c_complex = False
+
 def iter_integer_formats(byteorders=byteorders):
    for code in integer_codes:
        for byteorder in byteorders:
@@ -34,6 +44,34 @@ def bigendian_to_native(value):
        return string_reverse(value)

 class StructTest(unittest.TestCase):
+    # from Lib/test/test_complex.py
+    def assertFloatsAreIdentical(self, x, y):
+        """assert that floats x and y are identical, in the sense that:
+        (1) both x and y are nans, or
+        (2) both x and y are infinities, with the same sign, or
+        (3) both x and y are zeros, with the same sign, or
+        (4) x and y are both finite and nonzero, and x == y
+
+        """
+        msg = 'floats {!r} and {!r} are not identical'
+
+        if math.isnan(x) or math.isnan(y):
+            if math.isnan(x) and math.isnan(y):
+                return
+        elif x == y:
+            if x != 0.0:
+                return
+            # both zero; check that signs match
+            elif math.copysign(1.0, x) == math.copysign(1.0, y):
+                return
+            else:
+                msg += ': zeros have different signs'
+        self.fail(msg.format(x, y))
+
+    def assertComplexesAreIdentical(self, x, y):
+        self.assertFloatsAreIdentical(x.real, y.real)
+        self.assertFloatsAreIdentical(x.imag, y.imag)
+
    def test_isbigendian(self):
        self.assertEqual((struct.pack('=i', 1)[0] == 0), ISBIGENDIAN)

@@ -774,6 +812,17 @@ def test_repr(self):
        s = struct.Struct('=i2H')
        self.assertEqual(repr(s), f'Struct({s.format!r})')

+    @unittest.skipUnless(have_c_complex, "requires C11 complex type")
+    def test_c_complex_round_trip(self):
+        values = [complex(*_) for _ in combinations([1, -1, 0.0, -0.0, 2,
+                                                     -3, INF, -INF, NAN], 2)]
+        for z in values:
+            for f in ['E', 'C', '>E', '>C', '<E', '<C']:
+                with self.subTest(z=z, format=f):
+                    round_trip = struct.unpack(f, struct.pack(f, z))[0]
+                    self.assertComplexesAreIdentical(z, round_trip)
+
+
 class UnpackIteratorTest(unittest.TestCase):
    """
    Tests for iterative unpacking (struct.Struct.iter_unpack).

diff --git a/Misc/NEWS.d/next/Library/2024-07-10-08-13-34.gh-issue-121249.W9Gd09.rst b/Misc/NEWS.d/next/Library/2024-07-10-08-13-34.gh-issue-121249.W9Gd09.rst
@@ -0,0 +1,3 @@
+Support :c:expr:`float complex` and :c:expr:`double complex`
+C types in the :mod:`struct` if compiler has C11 complex
+arithmetic.  Patch by Sergey B Kirpichev.
-Original file line number
+Diff line change
@@ -267,12 +267,26 @@ platform-dependent.
     | ``P``  | :c:expr:`void \*`        | integer            |                | \(5)       |
     +--------+--------------------------+--------------------+----------------+------------+
+    Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is
                   skirpichev marked this conversation as resolved.
              

          
            Show resolved
            Hide resolved
        

                
  
            
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.
+    supported, the following format characters are available:
                   skirpichev marked this conversation as resolved.
              

          
            Show resolved
            Hide resolved
        

                
  
            
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.
+    +--------+--------------------------+--------------------+----------------+------------+
+    | Format | C Type                   | Python type        | Standard size  | Notes      |
+    +========+==========================+====================+================+============+
+    | ``E``  | :c:expr:`float complex`  | complex            | 8              | \(10)      |
+    +--------+--------------------------+--------------------+----------------+------------+
+    | ``C``  | :c:expr:`double complex` | complex            | 16             | \(10)      |
+    +--------+--------------------------+--------------------+----------------+------------+
     .. versionchanged:: 3.3
        Added support for the ``'n'`` and ``'N'`` formats.
     .. versionchanged:: 3.6
        Added support for the ``'e'`` format.
+    .. versionchanged:: 3.14
+       Added support for ``'E'`` and ``'C'`` formats.
                   skirpichev marked this conversation as resolved.
              

          
            Show resolved
            Hide resolved
        

                
  
            
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.
     Notes:
@@ -349,6 +363,11 @@ Notes:
        of bytes.  As a special case, ``'0s'`` means a single, empty string (while
        ``'0c'`` means 0 characters).
+    (10)
+       For the ``'E'`` and ``'C'`` conversion codes, the packed representation uses
                   skirpichev marked this conversation as resolved.
              

          
            Show resolved
            Hide resolved
        

                
  
            
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.
+       the IEEE 754 binary32 and binary64 format for components of the complex
                   skirpichev marked this conversation as resolved.
              

          
            Show resolved
            Hide resolved
        

                
  
            
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.
+       number, regardless of the floating-point format used by the platform.
     A format character may be preceded by an integral repeat count.  For example,
     the format string ``'4h'`` means exactly the same as ``'hhhh'``.
-          Expand Down