Merge branch 'master' of github.com:macdentalr12/cython into memview_to_c

docs/src/tutorial/numpy.rst

@@ -296,3 +296,42 @@ There is some speed penalty to this though (as one makes more assumptions
 compile-time if the type is set to :obj:`np.ndarray`, specifically it is
 assumed that the data is stored in pure strided mode and not in indirect
 mode).
+
+Pass data from a C function via pointer
+==================
+
+
+Since use of pointers in C is ubiquitous, here we give a quick example of how
+to call C functions whose arguments contain pointers.  Suppose you want to
+manage an array (allocate and deallocate) with NumPy, but its data are
+computed by an external C function declared in :file:`C_func_file.h`::
+    void C_func(double * CPointer, unsigned int N);
+
+where CPointer points to the array and N is its size.
+
+You can call the function in a Cython file in the following way::
+
+    cdef extern from "C_func_file.h":
+        void C_func(double *, unsigned int)
+
+    import cython
+    import numpy as np
+    cimport numpy as np
+
+    def f(arr): # 'arr' is a one-dimensional array of size N
+        # Before calling the external function, we need to check whether the
+        # memory for 'arr' is contiguous or not; if not, we store the computed
+        # data in an contiguous array and then copy the data from that array.
+        np.ndarray[np.double_t, ndim=1, mode="c"] contig_arr
+        if arr.flags.c_contiguous:
+            contig_arr = arr
+        else:
+            contig_arr = arr.copy('C')
+        C_func(<cython.double *> contig_arr.data, contig_arr.size)
+        if contig_arr is not arr:
+            arr[...] = contig_arr
+        return
+
+This way, you can have access the function more or less as a regular
+Python function while its data and associated memory gracefully managed
+by NumPy.