[pypy-commit] cffi default: Document ffi.memmove()

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2340:9d51e2cd2f08
Date: 2015-10-16 08:10 +0200
http://bitbucket.org/cffi/cffi/changeset/9d51e2cd2f08/

Log:	Document ffi.memmove()

diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -547,7 +547,8 @@
 
 On Win32, functions can have two main calling conventions: either
 "cdecl" (the default), or "stdcall" (also known as "WINAPI").  There
-are also other, rare calling conventions; these are not supported.
+are also other rare calling conventions, but these are not supported.
+*New in version 1.3.*
 
 When you issue calls from Python to C, the implementation is such that
 it works with any of these two main calling conventions; you don't
@@ -577,10 +578,11 @@
 These calling convention specifiers are accepted but ignored on any
 platform other than 32-bit Windows.
 
-*New in version 1.3:* the calling convention specifiers are not
-recognized in previous versions.  In API mode, you could work around
-it by using an indirection, like in the example in the section about
-Callbacks_.  There was no way to use stdcall callbacks in ABI mode.
+In CFFI versions before 1.3, the calling convention specifiers are not
+recognized.  In API mode, you could work around it by using an
+indirection, like in the example in the section about Callbacks_
+(``"example_build.py"``).  There was no way to use stdcall callbacks
+in ABI mode.
 
 
 FFI Interface
@@ -701,6 +703,27 @@
 ``ffi.from_buffer()`` is alive.  *New in version 0.9.*
 
 
+.. _memmove:
+
+**ffi.memmove(dest, src, n)**: copy ``n`` bytes from memory area
+``src`` to memory area ``dest``.  See examples below.  Inspired by the
+C functions ``memcpy()`` and ``memmove()``---like the latter, the
+areas can overlap.  Each of ``dest`` and ``src`` can be either a cdata
+pointer or a Python object supporting the buffer/memoryview interface.
+In the case of ``dest``, the buffer/memoryview must be writable.
+Unlike ``ffi.from_buffer()``, there are no restrictions on the type of
+buffer.  *New in version 1.3.*  Examples:
+
+* ``ffi.memmove(myptr, b"hello", 5)`` copies the 5 bytes of
+  ``b"hello"`` to the area that ``myptr`` points to.
+
+* ``ba = bytearray(100); ffi.memmove(ba, myptr, 100)`` copies 100
+  bytes from ``myptr`` into the bytearray ``ba``.
+
+* ``ffi.memmove(myptr + 1, myptr, 100)`` shifts 100 bytes from
+  the memory at ``myptr`` to the memory at ``myptr + 1``.
+
+
 **ffi.typeof("C type" or cdata object)**: return an object of type
 ``<ctype>`` corresponding to the parsed string, or to the C type of the
 cdata instance.  Usually you don't need to call this function or to
@@ -756,7 +779,7 @@
 of a pointer or array type.  For example, ``ffi.offsetof("int[5]", 2)``
 is equal to the size of two integers, as is ``ffi.offsetof("int *", 2)``.
 
-   
+
 **ffi.getctype("C type" or <ctype>, extra="")**: return the string
 representation of the given C type.  If non-empty, the "extra" string is
 appended (or inserted at the right place in more complicated cases); it
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -6,31 +6,33 @@
 v1.3.0
 ======
 
+* Added `ffi.memmove()`_.
+
 * Pull request #64: out-of-line API mode: we can now declare
   floating-point types with ``typedef float... foo_t;``.  This only
   works if ``foo_t`` is a float or a double, not ``long double``.
 
-* Issue #217: fix possible unaligned pointer manipulation, which crash
+* Issue #217: fix possible unaligned pointer manipulation, which crashes
   on some architectures (64-bit, non-x86).
 
 * Issues #64 and #126: when using ``set_source()`` or ``verify()``,
   the ``const`` and ``restrict`` keywords are copied from the cdef
   to the generated C code; this fixes warnings by the C compiler.
   It also fixes corner cases like ``typedef const int T; T a;``
-  which would previously not consider ``a`` as a constant.
+  which would previously not consider ``a`` as a constant.  (The
+  cdata objects themselves are never ``const``.)
 
 * Win32: support for ``__stdcall``.  For callbacks and function
-  pointers; regular C functions don't need to have their `calling
+  pointers; regular C functions still don't need to have their `calling
   convention`_ declared.
 
-* ffi.memmove XXX
-
 * Windows: CPython 2.7 distutils doesn't work with Microsoft's official
   Visual Studio for Python, and I'm told this is `not a bug`__.  For
   ffi.compile(), we `removed a workaround`__ that was inside cffi but
   which had unwanted side-effects.  Try saying ``import setuptools``
   first, which patches distutils...
 
+.. _`ffi.memmove()`: using.html#memmove
 .. __: https://bugs.python.org/issue23246
 .. __: https://bitbucket.org/cffi/cffi/pull-requests/65/remove-_hack_at_distutils-which-imports/diff
 .. _`calling convention`: using.html#windows-calling-conventions