diff options
author | Armin Rigo <arigo@tunes.org> | 2017-09-15 19:24:53 +0200 |
---|---|---|
committer | Armin Rigo <arigo@tunes.org> | 2017-09-15 19:24:53 +0200 |
commit | 47a5a1d8fde7a3f3239cdfe3b18e68d7441e7937 (patch) | |
tree | e2a93b2dd9a13c7cf76eb683d56dc314f13d3a1a /doc/source/using.rst | |
parent | 335dc1e24c2b400f68c6cf4c21dc585c4badff60 (diff) | |
download | cffi-47a5a1d8fde7a3f3239cdfe3b18e68d7441e7937.tar.gz |
Update the doc, as suggested on python-cffi
Diffstat (limited to 'doc/source/using.rst')
-rw-r--r-- | doc/source/using.rst | 31 |
1 files changed, 29 insertions, 2 deletions
diff --git a/doc/source/using.rst b/doc/source/using.rst index fc4ad5f..65f49ff 100644 --- a/doc/source/using.rst +++ b/doc/source/using.rst @@ -128,10 +128,37 @@ NULL>``, which you can check for e.g. by comparing it with There is no general equivalent to the ``&`` operator in C (because it would not fit nicely in the model, and it does not seem to be needed -here). But see `ffi.addressof()`__. +here). There is `ffi.addressof()`__, but only for some cases. You +cannot take the "address" of a number in Python, for example; similarly, +you cannot take the address of a CFFI pointer. If you have this kind +of C code:: + + int x, y; + fetch_size(&x, &y); + + opaque_t *handle; // some opaque pointer + init_stuff(&handle); // initializes the variable 'handle' + more_stuff(handle); // pass the handle around to more functions + +then you need to rewrite it like this, replacing the variables in C +with what is logically pointers to the variables: + +.. code-block:: python + + px = ffi.new("int *") + py = ffi.new("int *") arr = ffi.new("int[2]") + lib.fetch_size(px, py) -OR- lib.fetch_size(arr, arr + 1) + x = px[0] x = arr[0] + y = py[0] y = arr[1] + + p_handle = ffi.new("opaque_t **") + lib.init_stuff(p_handle) # pass the pointer to the 'handle' pointer + handle = p_handle[0] # now we can read 'handle' out of 'p_handle' + lib.more_stuff(handle) .. __: ref.html#ffi-addressof + Any operation that would in C return a pointer or array or struct type gives you a fresh cdata object. Unlike the "original" one, these fresh cdata objects don't have ownership: they are merely references to @@ -208,7 +235,7 @@ and calling ``ffi.string()`` on the cdata object returns the current unicode string stored in the source array (adding surrogates if necessary). See the `Unicode character types`__ section for more details. -__: ref.html#unichar +.. __: ref.html#unichar Note that unlike Python lists or tuples, but like C, you *cannot* index in a C array from the end using negative numbers. |