DOC: rename ReST files under doc/ from *.txt to *.rst.txt, so they render on github.

1 files changed, 313 insertions, 0 deletions

diff --git a/doc/CAPI.rst.txt b/doc/CAPI.rst.txt
new file mode 100644
index 000000000..41241ce5a
--- /dev/null
+++ b/doc/CAPI.rst.txt
@@ -0,0 +1,313 @@
+===============
+C-API for NumPy
+===============
+
+:Author:          Travis Oliphant
+:Discussions to:  `numpy-discussion@scipy.org`__
+:Created:         October 2005
+
+__ http://www.scipy.org/Mailing_Lists
+
+The C API of NumPy is (mostly) backward compatible with Numeric.
+
+There are a few non-standard Numeric usages (that were not really part
+of the API) that will need to be changed:
+
+* If you used any of the function pointers in the ``PyArray_Descr``
+  structure you will have to modify your usage of those.  First,
+  the pointers are all under the member named ``f``.  So ``descr->cast`` 
+  is now ``descr->f->cast``.  In addition, the
+  casting functions have eliminated the strides argument (use
+  ``PyArray_CastTo`` if you need strided casting). All functions have
+  one or two ``PyArrayObject *`` arguments at the end.  This allows the
+  flexible arrays and mis-behaved arrays to be handled.
+
+* The ``descr->zero`` and ``descr->one`` constants have been replaced with
+  function calls, ``PyArray_Zero``, and ``PyArray_One`` (be sure to read the
+  code and free the resulting memory if you use these calls).
+
+* If you passed ``array->dimensions`` and ``array->strides`` around
+  to functions, you will need to fix some code. These are now
+  ``npy_intp*`` pointers. On 32-bit systems there won't be a problem.
+  However, on 64-bit systems, you will need to make changes to avoid
+  errors and segfaults.
+
+
+The header files ``arrayobject.h`` and ``ufuncobject.h`` contain many defines
+that you may find useful.  The files ``__ufunc_api.h`` and
+``__multiarray_api.h`` contain the available C-API function calls with
+their function signatures.
+
+All of these headers are installed to
+``<YOUR_PYTHON_LOCATION>/site-packages/numpy/core/include``
+
+
+Getting arrays in C-code
+=========================
+
+All new arrays can be created using ``PyArray_NewFromDescr``.  A simple interface
+equivalent to ``PyArray_FromDims`` is ``PyArray_SimpleNew(nd, dims, typenum)``
+and to ``PyArray_FromDimsAndData`` is
+``PyArray_SimpleNewFromData(nd, dims, typenum, data)``.
+
+This is a very flexible function.
+
+::
+
+  PyObject * PyArray_NewFromDescr(PyTypeObject *subtype, PyArray_Descr *descr,
+                                int nd, npy_intp *dims,
+                                npy_intp *strides, char *data,
+                                int flags, PyObject *obj);
+
+``subtype`` : ``PyTypeObject *``
+    The subtype that should be created (either pass in
+    ``&PyArray_Type``,  or ``obj->ob_type``,
+    where ``obj`` is a an instance of a subtype (or subclass) of
+    ``PyArray_Type``).
+
+``descr`` : ``PyArray_Descr *``
+    The type descriptor for the array. This is a Python object (this
+    function steals a reference to it). The easiest way to get one is
+    using ``PyArray_DescrFromType(<typenum>)``. If you want to use a
+    flexible size array, then you need to use
+    ``PyArray_DescrNewFromType(<flexible typenum>)`` and set its ``elsize``
+    paramter to the desired size. The typenum in both of these cases
+    is one of the ``PyArray_XXXX`` enumerated types.
+
+``nd`` : ``int``
+    The number of dimensions (<``MAX_DIMS``)
+
+``*dims`` : ``npy_intp *``
+    A pointer to the size in each dimension. Information will be
+    copied from here.
+
+``*strides`` : ``npy_intp *``
+    The strides this array should have. For new arrays created by this
+    routine, this should be ``NULL``. If you pass in memory for this array
+    to use, then you can pass in the strides information as well
+    (otherwise it will be created for you and default to C-contiguous
+    or Fortran contiguous). Any strides will be copied into the array
+    structure. Do not pass in bad strides information!!!!
+
+    ``PyArray_CheckStrides(...)`` can help but you must call it if you are
+    unsure. You cannot pass in strides information when data is ``NULL``
+    and this routine is creating its own memory.
+
+``*data`` : ``char *``
+    ``NULL`` for creating brand-new memory. If you want this array to wrap
+    another memory area, then pass the pointer here. You are
+    responsible for deleting the memory in that case, but do not do so
+    until the new array object has been deleted. The best way to
+    handle that is to get the memory from another Python object,
+    ``INCREF`` that Python object after passing it's data pointer to this
+    routine, and set the ``->base`` member of the returned array to the
+    Python object. *You are responsible for* setting ``PyArray_BASE(ret)``
+    to the base object. Failure to do so will create a memory leak.
+
+    If you pass in a data buffer, the ``flags`` argument will be the flags
+    of the new array. If you create a new array, a non-zero flags
+    argument indicates that you want the array to be in Fortran order.
+
+``flags`` : ``int``
+    Either the flags showing how to interpret the data buffer passed
+    in, or if a new array is created, nonzero to indicate a Fortran
+    order array. See below for an explanation of the flags.
+
+``obj`` : ``PyObject *``
+    If subtypes is ``&PyArray_Type``, this argument is
+    ignored. Otherwise, the ``__array_finalize__`` method of the subtype
+    is called (if present) and passed this object. This is usually an
+    array of the type to be created (so the ``__array_finalize__`` method
+    must handle an array argument. But, it can be anything...)
+
+Note: The returned array object will be unitialized unless the type is
+``PyArray_OBJECT`` in which case the memory will be set to ``NULL``.
+
+``PyArray_SimpleNew(nd, dims, typenum)`` is a drop-in replacement for
+``PyArray_FromDims`` (except it takes ``npy_intp*`` dims instead of ``int*`` dims
+which matters on 64-bit systems) and it does not initialize the memory
+to zero.
+
+``PyArray_SimpleNew`` is just a macro for ``PyArray_New`` with default arguments.
+Use ``PyArray_FILLWBYTE(arr, 0)``  to fill with zeros.
+
+The ``PyArray_FromDims`` and family of functions are still available and
+are loose wrappers around this function.  These functions still take
+``int *`` arguments.  This should be fine on 32-bit systems, but on 64-bit
+systems you may run into trouble if you frequently passed
+``PyArray_FromDims`` the dimensions member of the old ``PyArrayObject`` structure
+because ``sizeof(npy_intp) != sizeof(int)``.
+
+
+Getting an arrayobject from an arbitrary Python object
+======================================================
+
+``PyArray_FromAny(...)``
+
+This function replaces ``PyArray_ContiguousFromObject`` and friends (those
+function calls still remain but they are loose wrappers around the
+``PyArray_FromAny`` call).
+
+::
+
+  static PyObject *
+  PyArray_FromAny(PyObject *op, PyArray_Descr *dtype, int min_depth,
+  		  int max_depth, int requires, PyObject *context)
+
+
+``op`` : ``PyObject *``
+    The Python object to "convert" to an array object
+
+``dtype`` : ``PyArray_Descr *``
+    The desired data-type descriptor. This can be ``NULL``, if the
+    descriptor should be determined by the object. Unless ``FORCECAST`` is
+    present in ``flags``, this call will generate an error if the data
+    type cannot be safely obtained from the object.
+
+``min_depth`` : ``int``
+    The minimum depth of array needed or 0 if doesn't matter
+
+``max_depth`` : ``int``
+    The maximum depth of array allowed or 0 if doesn't matter
+
+``requires`` : ``int``
+    A flag indicating the "requirements" of the returned array. These
+    are the usual ndarray flags (see `NDArray flags`_ below). In
+    addition, there are three flags used only for the ``FromAny``
+    family of functions:
+
+      - ``ENSURECOPY``: always copy the array. Returned arrays always
+        have ``CONTIGUOUS``, ``ALIGNED``, and ``WRITEABLE`` set.
+      - ``ENSUREARRAY``: ensure the returned array is an ndarray (or a
+        bigndarray if ``op`` is one).
+      - ``FORCECAST``: cause a cast to occur regardless of whether or
+        not it is safe.
+
+``context`` : ``PyObject *``
+    If the Python object ``op`` is not an numpy array, but has an
+    ``__array__`` method, context is passed as the second argument to
+    that method (the first is the typecode). Almost always this
+    parameter is ``NULL``.
+
+
+``PyArray_ContiguousFromAny(op, typenum, min_depth, max_depth)`` is
+equivalent to ``PyArray_ContiguousFromObject(...)`` (which is still
+available), except it will return the subclass if op is already a
+subclass of the ndarray. The ``ContiguousFromObject`` version will
+always return an ndarray (or a bigndarray).
+
+Passing Data Type information to C-code
+=======================================
+
+All datatypes are handled using the ``PyArray_Descr *`` structure.
+This structure can be obtained from a Python object using
+``PyArray_DescrConverter`` and ``PyArray_DescrConverter2``.  The former
+returns the default ``PyArray_LONG`` descriptor when the input object
+is None, while the latter returns ``NULL`` when the input object is ``None``.
+
+See the ``arraymethods.c`` and ``multiarraymodule.c`` files for many
+examples of usage.
+
+Getting at the structure of the array.
+--------------------------------------
+
+You should use the ``#defines`` provided to access array structure portions:
+
+- ``PyArray_DATA(obj)`` : returns a ``void *`` to the array data
+- ``PyArray_BYTES(obj)`` : return a ``char *`` to the array data
+- ``PyArray_ITEMSIZE(obj)``
+- ``PyArray_NDIM(obj)``
+- ``PyArray_DIMS(obj)``
+- ``PyArray_DIM(obj, n)``
+- ``PyArray_STRIDES(obj)``
+- ``PyArray_STRIDE(obj,n)``
+- ``PyArray_DESCR(obj)``
+- ``PyArray_BASE(obj)``
+
+see more in ``arrayobject.h``
+
+
+NDArray Flags
+=============
+
+The ``flags`` attribute of the ``PyArrayObject`` structure contains important
+information about the memory used by the array (pointed to by the data member)
+This flags information must be kept accurate or strange results and even
+segfaults may result.
+
+There are 6 (binary) flags that describe the memory area used by the
+data buffer.  These constants are defined in ``arrayobject.h`` and
+determine the bit-position of the flag.  Python exposes a nice attribute-
+based interface as well as a dictionary-like interface for getting 
+(and, if appropriate, setting) these flags.
+
+Memory areas of all kinds can be pointed to by an ndarray, necessitating
+these flags.  If you get an arbitrary ``PyArrayObject`` in C-code,
+you need to be aware of the flags that are set.
+If you need to guarantee a certain kind of array
+(like ``NPY_CONTIGUOUS`` and ``NPY_BEHAVED``), then pass these requirements into the
+PyArray_FromAny function.
+
+
+``NPY_CONTIGUOUS``
+    True if the array is (C-style) contiguous in memory.
+``NPY_FORTRAN``
+    True if the array is (Fortran-style) contiguous in memory.
+
+Notice that contiguous 1-d arrays are always both ``NPY_FORTRAN`` contiguous 
+and C contiguous. Both of these flags can be checked and are convenience
+flags only as whether or not an array is ``NPY_CONTIGUOUS`` or ``NPY_FORTRAN``
+can be determined by the ``strides``, ``dimensions``, and ``itemsize``
+attributes.
+
+``NPY_OWNDATA``
+    True if the array owns the memory (it will try and free it using
+    ``PyDataMem_FREE()`` on deallocation --- so it better really own it).
+
+These three flags facilitate using a data pointer that is a memory-mapped
+array, or part of some larger record array.  But, they may have other uses...
+
+``NPY_ALIGNED``
+    True if the data buffer is aligned for the type and the strides
+    are multiples of the alignment factor as well.  This can be
+    checked.
+
+``NPY_WRITEABLE``
+    True only if the data buffer can be "written" to.
+
+``NPY_UPDATEIFCOPY``
+    This is a special flag that is set if this array represents a copy
+    made because a user required certain flags in ``PyArray_FromAny`` and
+    a copy had to be made of some other array (and the user asked for
+    this flag to be set in such a situation). The base attribute then
+    points to the "misbehaved" array (which is set read_only). When
+    the array with this flag set is deallocated, it will copy its
+    contents back to the "misbehaved" array (casting if necessary) and
+    will reset the "misbehaved" array to ``WRITEABLE``. If the
+    "misbehaved" array was not ``WRITEABLE`` to begin with then
+    ``PyArray_FromAny`` would have returned an error because ``UPDATEIFCOPY``
+    would not have been possible.
+
+
+``PyArray_UpdateFlags(obj, flags)`` will update the ``obj->flags`` for
+``flags`` which can be any of ``NPY_CONTIGUOUS``, ``NPY_FORTRAN``, ``NPY_ALIGNED``, or
+``NPY_WRITEABLE``.
+
+Some useful combinations of these flags:
+
+- ``NPY_BEHAVED = NPY_ALIGNED | NPY_WRITEABLE``
+- ``NPY_CARRAY = NPY_DEFAULT = NPY_CONTIGUOUS | NPY_BEHAVED``
+- ``NPY_CARRAY_RO = NPY_CONTIGUOUS | NPY_ALIGNED``
+- ``NPY_FARRAY = NPY_FORTRAN | NPY_BEHAVED``
+- ``NPY_FARRAY_RO = NPY_FORTRAN | NPY_ALIGNED``
+
+The macro ``PyArray_CHECKFLAGS(obj, flags)``  can test any combination of flags.
+There are several default combinations defined as macros already
+(see ``arrayobject.h``)
+
+In particular, there are ``ISBEHAVED``, ``ISBEHAVED_RO``, ``ISCARRAY``
+and ``ISFARRAY`` macros that also check to make sure the array is in
+native byte order (as determined) by the data-type descriptor.
+
+There are more C-API enhancements which you can discover in the code,
+or buy the book (http://www.trelgol.com)