[Numpy-svn] r3217 - trunk/numpy

[numpy-svn at scipy.org]

Author: stefan
Date: 2006-09-26 06:20:17 -0500 (Tue, 26 Sep 2006)
New Revision: 3217

Modified:
   trunk/numpy/ctypeslib.py
Log:
Draft documentation for ndpointer.


Modified: trunk/numpy/ctypeslib.py
===================================================================
--- trunk/numpy/ctypeslib.py	2006-09-25 17:51:52 UTC (rev 3216)
+++ trunk/numpy/ctypeslib.py	2006-09-26 11:20:17 UTC (rev 3217)
@@ -80,6 +80,29 @@
 #  use with ctypes argtypes mechanism
 _pointer_type_cache = {}
 def ndpointer(dtype=None, ndim=None, shape=None, flags=None):
+    """Array-checking restype/argtypes.
+    
+    An ndpointer instance is used to describe an ndarray in restypes
+    and argtypes specifications.  This approach is more flexible than
+    using, for example,
+    
+    POINTER(c_double)
+    
+    since several restrictions can be specified, which are verified
+    upon calling the ctypes function.  These include data type
+    (dtype), number of dimensions (ndim), shape and flags (e.g.
+    'CONTIGUOUS' or 'FORTRAN').  If a given array does not satisfy the
+    specified restrictions, a TypeError is raised.
+    
+    Example:
+        
+        clib.somefunc.argtypes = [ndpointer(dtype=float64,
+                                            ndim=1,
+                                            flags='CONTIGUOUS')]
+        clib.somefunc(array([1,2,3],dtype=float64))
+
+    """
+    
     if dtype is not None:
         dtype = _dtype(dtype)
     num = None