[pypy-commit] cffi sirtom67/float_complex: Documentation
arigo
pypy.commits at gmail.com
Tue May 30 13:10:22 EDT 2017
Author: Armin Rigo <arigo at tunes.org>
Branch: sirtom67/float_complex
Changeset: r2946:927b4c3bbd9a
Date: 2017-05-30 19:09 +0200
http://bitbucket.org/cffi/cffi/changeset/927b4c3bbd9a/
Log: Documentation
diff --git a/c/test_c.py b/c/test_c.py
--- a/c/test_c.py
+++ b/c/test_c.py
@@ -228,6 +228,12 @@
assert type(x[5]) is complex
assert abs(x[5] - (12.34 + 56.78j)) < 1e-5
assert (x[5] == 12.34 + 56.78j) == (name == "double") # rounding error
+ #
+ class Foo:
+ def __complex__(self):
+ return 2 + 3j
+ assert complex(Foo()) == 2 + 3j
+ assert complex(cast(p, Foo())) == 2 + 3j
py.test.raises(TypeError, cast, new_primitive_type("int"), 1+0j)
def test_character_type():
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -642,16 +642,15 @@
* Any ``__attribute__`` or ``#pragma pack(n)``
-* Additional types: complex numbers, special-size floating and fixed
- point types, vector types, and so on. You might be able to access an
- array of complex numbers by declaring it as an array of ``struct
- my_complex { double real, imag; }``, but in general you should declare
- them as ``struct { ...; }`` and cannot access them directly. This
- means that you cannot call any function which has an argument or
- return value of this type (this would need added support in libffi).
- You need to write wrapper functions in C, e.g. ``void
- foo_wrapper(struct my_complex c) { foo(c.real + c.imag*1j); }``, and
- call ``foo_wrapper`` rather than ``foo`` directly.
+* Additional types: special-size floating and fixed
+ point types, vector types, and so on.
+
+* The C99 types ``float _Complex`` and ``double _Complex`` are supported
+ by cffi since version 1.11, but not libffi: you cannot call C
+ functions with complex arguments or return value, except if they are
+ directly API-mode functions. The type ``long double _Complex`` is not
+ supported at all (declare and use it as if it were an array of two
+ ``long double``, and write wrapper functions in C with set_source()).
Note that declarations like ``int field[];`` in
structures are interpreted as variable-length structures. Declarations
diff --git a/doc/source/ref.rst b/doc/source/ref.rst
--- a/doc/source/ref.rst
+++ b/doc/source/ref.rst
@@ -618,8 +618,8 @@
| C type | writing into | reading from |other operations|
+===============+========================+==================+================+
| integers | an integer or anything | a Python int or | int(), bool() |
-| and enums | on which int() works | long, depending | `(******)`, |
-| `(*****)` | (but not a float!). | on the type | ``<`` |
+| and enums | on which int() works | long, depending | `[6]`, |
+| `[5]` | (but not a float!). | on the type | ``<`` |
| | Must be within range. | (ver. 1.10: or a | |
| | | bool) | |
+---------------+------------------------+------------------+----------------+
@@ -636,14 +636,19 @@
+---------------+------------------------+------------------+----------------+
|``long double``| another <cdata> with | a <cdata>, to | float(), int(),|
| | a ``long double``, or | avoid loosing | bool() |
-| | anything on which | precision `(***)`| |
+| | anything on which | precision `[3]` | |
| | float() works | | |
+---------------+------------------------+------------------+----------------+
-| pointers | another <cdata> with | a <cdata> |``[]`` `(****)`,|
+| ``float`` | a complex number | a Python complex | complex(), |
+| ``_Complex``, | or anything on which | number | bool() |
+| ``double`` | complex() works | | `[7]` |
+| ``_Complex`` | | | |
++---------------+------------------------+------------------+----------------+
+| pointers | another <cdata> with | a <cdata> |``[]`` `[4]`, |
| | a compatible type (i.e.| |``+``, ``-``, |
| | same type | |bool() |
| | or ``void*``, or as an | | |
-| | array instead) `(*)` | | |
+| | array instead) `[1]` | | |
+---------------+------------------------+ | |
| ``void *`` | another <cdata> with | | |
| | any pointer or array | | |
@@ -655,10 +660,10 @@
| | | | struct fields |
+---------------+------------------------+ +----------------+
| function | same as pointers | | bool(), |
-| pointers | | | call `(**)` |
+| pointers | | | call `[2]` |
+---------------+------------------------+------------------+----------------+
| arrays | a list or tuple of | a <cdata> |len(), iter(), |
-| | items | |``[]`` `(****)`,|
+| | items | |``[]`` `[4]`, |
| | | |``+``, ``-`` |
+---------------+------------------------+ +----------------+
| ``char[]``, | same as arrays, or a | | len(), iter(), |
@@ -680,7 +685,7 @@
| | with at most one field | | fields |
+---------------+------------------------+------------------+----------------+
-`(*)` ``item *`` is ``item[]`` in function arguments:
+`[1]` ``item *`` is ``item[]`` in function arguments:
In a function declaration, as per the C standard, a ``item *``
argument is identical to a ``item[]`` argument (and ``ffi.cdef()``
@@ -701,7 +706,7 @@
(On PyPy, this optimization is only available since PyPy 5.4
with CFFI 1.8.)
-`(**)` C function calls are done with the GIL released.
+`[2]` C function calls are done with the GIL released.
Note that we assume that the called functions are *not* using the
Python API from Python.h. For example, we don't check afterwards
@@ -713,7 +718,7 @@
``libpypy-c.dll`` on their own. But really, don't do that in the
first place.)
-`(***)` ``long double`` support:
+`[3]` ``long double`` support:
We keep ``long double`` values inside a cdata object to avoid
loosing precision. Normal Python floating-point numbers only
@@ -724,7 +729,7 @@
and use a family of C functions like ``long double add(long double
a, long double b);``.
-`(****)` Slicing with ``x[start:stop]``:
+`[4]` Slicing with ``x[start:stop]``:
Slicing is allowed, as long as you specify explicitly both ``start``
and ``stop`` (and don't give any ``step``). It gives a cdata
@@ -738,7 +743,7 @@
say ``chararray[10:15] = "hello"``, but the assigned string must be of
exactly the correct length; no implicit null character is added.)
-`(*****)` Enums are handled like ints:
+`[5]` Enums are handled like ints:
Like C, enum types are mostly int types (unsigned or signed, int or
long; note that GCC's first choice is unsigned). Reading an enum
@@ -747,7 +752,7 @@
lib.FOO``. If you really want to get their value as a string, use
``ffi.string(ffi.cast("the_enum_type", x.field))``.
-`(******)` bool() on a primitive cdata:
+`[6]` bool() on a primitive cdata:
*New in version 1.7.* In previous versions, it only worked on
pointers; for primitives it always returned True.
@@ -760,6 +765,13 @@
Also, when converting from a byte string to a ``_Bool[]``, only the
bytes ``\x00`` and ``\x01`` are accepted.
+`[7]` libffi does not support complex numbers:
+
+ *New in version 1.11:* CFFI now supports complex numbers directly.
+ Note however that libffi does not. This means that C functions that
+ take directly as argument types or return type a complex type cannot
+ be called by CFFI, unless they are directly using the API mode.
+
.. _file:
Support for FILE
More information about the pypy-commit
mailing list