\chapter{C extension API}
\label{cha:C-API}

\begin{quote}
   This chapter describes the different available C-APIs for \module{numarray}
   based extension modules.
\end{quote}

While this chapter describes the \module{\numarray}-specifics for writing
extension modules, a basic understanding of \python extension modules is
expected. See \python's \ulink{Extending and
   Embedding}{http://www.python.org/doc/current/ext/ext.html} tutorial and the
\ulink{Python/C API}{http://www.python.org/doc/current/api/api.html}.

The numarray C-API has several different facets, and the first three facets
each make different tradeoffs between memory use, speed, and ease of use.  An
additional facet provides backwards compatability with legacy Numeric code.
The final facet consists of miscellaneous function calls used to implement
and utilize numarray, that were not part of Numeric.

In addition to most of the basic functionality provided by Numeric, these APIs
provide access to misaligned, byteswapped, and discontiguous \class{numarray}s.
Byteswapped arrays arise in the context of portable binary data formats where
the byteorder specified by the data format is not the same as the host
processor byte order.  Misaligned arrays arise in the context of tabular data:
files of records where arrays are superimposed on the column formed by a single
field in the record.  Discontiguous arrays arise from operations which permute
the shape and strides of an array, such as reshape.

\begin{description}

\item[high-level] This is the cleanest and eaisiest to use API.  It creates
   temporary arrays to handle difficult cases (discontiguous, byteswapped,
   misaligned) in C code.  Code using this API is written in terms of a pointer
   to a contiguous 1D array of C data.  See section
   \ref{sec:C-API:high-level-api}.
\item[element-wise] This API handles misbehaved arrays without creating
     temporaries.  Code using this API is written to access single elements of
     an array via macros or functions.  \note{These macros are probably slow,
     and the functions even slower.} See section
     \ref{sec:C-API:element-wise-api}.
\item[1-dimensional] Code using this API get/sets consecutive elements of the
   inner dimension of an array, enabling the API to factor out tests for
   aligment and byteswapping to one test per call.  Fewer tests means better
   performance,  but at a cost of some temporary data and more difficult usage.
   See section \ref{sec:C-API:One-dimensional-api}.
\item[Numeric compatability functions] This API aims to provide a reasonable
   (if not complete) emulation of the Numeric C-API.  It is written in terms of
   the numarray high level API so that misbehaved numarrays are copied prior to
   processing with legacy Numeric code.  See section
   \ref{sec:C-API:numeric-emulation}.
\item[New numarray functions] This last facet of the C-API consists of function
  calls which have been added to numarray which are orthogonal to each of the 3
  native access APIs and not part of the original Numeric. See section
  \ref{sec:C-API:new-numarray-functions}
\end{description}

\section{Accessing the numarray C-API}
There's a couple things you need to do in order to access numarray's C-API in
your own C extension module:

\subsection{include numarray.h}
  
  Near the top of your extension module add the line:
\begin{verbatim}
#include "numarray.h"
\end{verbatim} 
  This gives your C-code access to the numarray typedefs, macros, and function
  prototypes.

\subsection{import libnumarray}
  
  In your extension module's initialization function, add the line:
\begin{verbatim}
  import_libnumarray();
\end{verbatim} 
  
  import_libnumarray() is actually a macro which sets up a pointer to the
  numarray C-API jump table. If you forget to call import_libnumarray(), your
  extension module will crash as soon as you call a numarray API function,
  because your application will attempt to dereference a NULL pointer.  

  Note that there is also a Numeric compatible API which substitutes
  arrayobject.h for numarray.h and import_array() for import_libnumarray()
  respectively.
  
\section{Fundamental data structures}
\label{C-API:fundamental-data-structures}

\subsection{Numarray Numerical Data Types}

Numarray hides the C implementation of its basic array elements behind a set of
C typedefs which specify the absolute size of the type in bits.  This approach
enables a programmer to specify data items of arrays and extension functions in
an explicit yet portable manner.  In contrast, basic C types are platform
relative, and so less useful for describing real physical data.  Here are the
names of the concrete Numarray element types:

\begin{itemize}
\item Bool                
\item Int8,      UInt8
\item Int16,     UInt16
\item Int32,     UInt32
\item Int64,     UInt64
\item Float32,   Float64
\item Complex32, Complex64
\end{itemize}

\subsection{NumarrayType}

The type of a numarray is communicated in C via one of the following
enumeration constants.  Type codes which are backwards compatible with Numeric
are defined in terms of these constants, but use these if you're not already
using the Numeric codes.  These constants communicate type requirements between
one function and another, since in C, you cannot pass a typedef as a value.
tAny is used to specify both ``no type requirement'' and ``no known type''
depending on context.   

\begin{verbatim}
typedef enum 
{
  tAny,

  tBool,
  tInt8,      tUInt8,
  tInt16,     tUInt16,
  tInt32,     tUInt32, 
  tInt64,     tUInt64,
  tFloat32,   tFloat64,
  tComplex32, tComplex64,

  tDefault = tFloat64,

#if LP64
  tLong = tInt64
#else
  tLong = tInt32
#endif

} NumarrayType;
\end{verbatim}

\subsection{PyArray_Descr}

\ctype{PyArray_Descr} is used to hold a few parameters related to the type of
an array and exists mostly for backwards compatability with Numeric.
\var{type_num} is a NumarrayType value.  \var{elsize} indicates the number of
bytes in one element of an array of that type.  \var{type} is a Numeric
compatible character code.

Numarray's \ctype{PyArray_Descr} is currently missing the type-casting,
\function{ones}, and \function{zeroes} functions.  Extensions which use these
missing Numeric features will not yet compile.  Arrays of type Object are not
yet supported.

\begin{verbatim}

typedef struct {
        int  type_num;  /* PyArray_TYPES */
        int  elsize;    /* bytes for 1 element */
        char type;      /* One of "cb1silfdFD "  Object arrays not supported. */
} PyArray_Descr;

\end{verbatim}

\subsection{PyArrayObject}

The fundamental data structure of numarray is the PyArrayObject, which is named
and layed out to maximize compatability with Numeric.  The numarray version of
PyArrayObject is compile-time compatible with most but not all Numeric code.
The constant MAXDIM, the maximum number of dimensions in an array, is typically
defined as 40.  It should be noted that unlike earlier versions of numarray,
the present PyArrayObject structure is a first class python object, with full
support for the number protocols in C.  Well-behaved arrays have mutable fields
which will reflect modifications back into \python ``for free''.

\begin{verbatim}

typedef int maybelong;          /* towards 64-bit without breaking extensions. */

typedef struct {
        /* Numeric compatible stuff */

        PyObject_HEAD
        char *data;              /* points to the actual C data for the array */
        int nd;                  /* number of array shape elements */
        maybelong dimensions[MAXDIM];  /* values of shape elements */
        maybelong strides[MAXDIM];     /* values of stride elements */
        PyObject *base;          /* unused, but don't touch! */
        PyArray_Descr *descr;    /* pointer to descriptor for this array's type */
        int flags;               /* bitmask defining various array properties */

        /* numarray extras */

        PyObject *_data;       /* object must meet buffer API */
        PyObject *_shadows;    /* ill-behaved original array. */
        int      nstrides;     /* elements in strides array */
        long     byteoffset;   /* offset into buffer where array data begins */
        long     bytestride;   /* basic seperation of elements in bytes */
        long     itemsize;     /* length of 1 element in bytes */

        char      byteorder;   /* NUM_BIG_ENDIAN, NUM_LITTLE_ENDIAN */

        char      _aligned;    /* test override flag */      
        char      _contiguous; /* test override flag */
        
        /* Don't expect the following vars to stay around.  Never use them.
        They're an implementation detail of the get/set macros. */

        Complex64      temp;   /* temporary for get/set macros */
        char *         wptr;   /* working pointer for get/set macros */
} PyArrayObject;

\end{verbatim}

\subsection{Flag Bits}

The following are the definitions for the bit values in the \var{flags} field
of each numarray.  Low order bits are Numeric compatible,  higher order bits
were added by numarray.

\begin{verbatim}
/* Array flags */
#define CONTIGUOUS        1       /* compatible, depends */
#define OWN_DIMENSIONS    2       /* always false */
#define OWN_STRIDES       4       /* always false */
#define OWN_DATA          8       /* always false */
#define SAVESPACE      0x10       /* not used */

#define ALIGNED       0x100       /* roughly: data % itemsize == 0 */
#define NOTSWAPPED    0x200       /* byteorder == sys.byteorder    */
#define WRITABLE      0x400       /* data buffer is writable       */

#define IS_CARRAY (CONTIGUOUS | ALIGNED | NOTSWAPPED)
\end{verbatim}

\section{High-level API}
\label{sec:C-API:high-level-api}

The high-level native API accepts an object (which may or may not be an array)
and transforms the object into an array which satisfies a set of ``behaved-ness
requirements''.  The idea behind the high-level API is to transparently convert
misbehaved numarrays, ordinary sequences, and python scalars into C-arrays.  A
``misbehaved array'' is one which is byteswapped, misaligned, or discontiguous.
This API is the simplest and fastest, provided that your arrays are small.  If
you find your program is exhausting all available memory, it may be time to
look at one of the other APIs.

\subsection{High-level functions}
\label{sec:C-API:high-level-functions}

The high-level support functions for interchanging \class{numarray}s between
\python{} and C are as follows:

\begin{cfuncdesc}{PyArrayObject*}{NA_InputArray}{%
      PyObject *numarray, NumarrayType t, int requires}
The purpose of NA_InputArray is to transfer array data from \python to C.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArrayObject*}{NA_OutputArray}{%
      PyObject *numarray, NumarrayType t, int requires}
The purpose of NA_OutputArray is to transfer data from C to \python.
Practically speaking, the output numarray must be a PyArrayObject, and
cannot be an arbitrary Python sequence.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArrayObject*}{NA_IoArray}{%
      PyObject *numarray, NumarrayType t, int requires} NA_IoArray has fully
bidirectional data transfer, creating the illusion of call-by-reference.
\end{cfuncdesc}

  For a well-behaved array, there is no difference between the three, as no
  temporary is created and the returned object is identical to the original
  object (with an additional reference).  For a mis-behaved input array, a
  well-behaved temporary will be created and the data copied from the original
  to the temporary.  Since it is an input, modifications to its contents are
  not guaranteed to be reflected back to \python, and in the case where a
  temporary was created, won't be.  For a mis-behaved output array, any data
  side-effects generated by the C code will be safely communicated back to
  \python, but the initial \class{numarray} contents are undefined.  For an I/O
  array, any required temporary will be initialized to the same contents as the
  original \class{numarray}, and any side-effects caused by C-code will be
  copied back to the original numarray.  The array factory routines of the
  Numeric compatability API are written in terms of NA_IoArray.
   
   The return value of each function (\cfunction{NA_InputArray},
   \cfunction{NA_OutputArray}, or \cfunction{NA_IoArray}) is either a reference
   to the original \class{numarray} object, or a reference to a temporary
   \class{numarray}.  Following execution of the C-code in the extension
   function body this pointer should \emph{always} be DECREFed.  When a
   temporary is DECREFed, it is deallocated, possibly after copying itself onto
   the original array.  The one exception to this rule is that you should not
   DECREF an array returned via the NA_ReturnOutput function.
   
   The \var{numarray} parameter specifies the original \class{numarray} object
   to be interfaced.  Nested lists and tuples of numbers can be converted by
   \cfunction{NA_InputArray} and \cfunction{NA_IoArray} into a temporary
   \class{numarray}.  The temporary is lost on function exit.  Strictly
   speaking, allowing NA_IoArray to accept a list or tuple is a wart, since it
   will lose any side effects.  In principle however, communication back to
   lists and tuples can be supported even though it is not currently.
   
   The \class{NumarrayType} \var{t} is an enumeration value which defines the
   type the array data should be converted to.  Arrays of the same type are
   passed through unaltered, while mis-matched arrays are cast into temporaries
   of the specified type.  The value \constant{tAny} may be specified to
   indicate that the extension function can handle any type correctly.
   
   The \var{requires} integer indicates under what conditions a temporary
   should be made.  The simple way to specify it is to use
   \constant{NUM_C_ARRAY}.  This will cause the API function to make a
   well-behaved temporary if the original is byteswapped, misaligned, or
   discontiguous.  

There is one other pair of high level function which serves to return output
arrays as the function value: NA_OptionalOutputArray and NA_ReturnOutput.

\begin{cfuncdesc}{PyArrayObject*}{NA_OptionalOutputArray}{%
      PyObject *numarray, NumarrayType t, int requires, PyObject *master}%
   \cfunction{NA_OptionalOutputArray} is essentially
   \cfunction{NA_OutputArray}, but with one twist: if the original array
   \var{numarray} has the value \constant{NULL} or \constant{Py_None}, a
   temporary copy of \class{numarray} \var{master} is returned.  This
   facilitates writing functions where the output array may or may-not be
   specified by the \python{} user.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{NA_ReturnOutput}{PyObject *numarray, PyObject *shadow}
   \cfunction{NA_ReturnOutput} accepts as parameters both the original
   \var{numarray} and the value returned from
   \cfunction{NA_OptionalOutputArray}, \var{shadow}.  If \var{numarray} is
   \constant{Py_None} or \constant{NULL}, then \var{shadow} is returned.
   Otherwise, an output array was specified by the user, and \constant{Py_None}
   is returned.  This facilitates writing functions in the numarray style
   where the specification of an output array renders the function ``mute'',
   with all side-effects in the output array and None as the return value.
\end{cfuncdesc}

\subsection{Behaved-ness Requirements}

Calls to the high level API specify a set of requirements that incoming arrays
must satisfy.  The requirements set is specified by a bit mask which is or'ed
together from bits representing individual array requirements.  An ordinary C
array satisfies all 3 requirements: it is contiguous, aligned, and not
byteswapped.  It is possible to request arrays satisfying any or none of the
behavedness requirements.  Arrays which do not satisfy the specified
requirements are transparently ``shadowed'' by temporary arrays which do
satisfy them.  By specifying NUM_UNCONVERTED, a caller is certifying that his
extension function can correctly and directly handle the special cases possible
for a \class{NumArray}, excluding type differences.

\begin{verbatim}
typedef enum
{
        NUM_CONTIGUOUS=1,
        NUM_NOTSWAPPED=2,
        NUM_ALIGNED=4,
        NUM_WRITABLE=8,

        NUM_C_ARRAY  = (NUM_CONTIGUOUS | NUM_ALIGNED | NUM_NOTSWAPPED),
        NUM_UNCONVERTED = 0
}
\end{verbatim}

\subsection{Example}
\label{sec:C-API:high-level:example}

A C wrapper function using the high-level API would typically look like the
following.\footnote{This function is taken from the convolve example in the
source distribution.}

\begin{verbatim}
static PyObject *
Py_Convolve1d(PyObject *obj, PyObject *args)
{
        PyObject   *okernel, *odata, *oconvolved=Py_None;
        PyArrayObject *kernel, *data, *convolved;

        if (!PyArg_ParseTuple(args, "OO|O", &okernel, &odata, &oconvolved)) {
                PyErr_Format(_convolveError, 
                             "Convolve1d: Invalid parameters.");
                goto _fail;
        }

\end{verbatim}

First, define local variables and parse parameters.  \cfunction{Py_Convolve1d}
expects two or three array parameters in \var{args}: the convolution kernel,
the data, and optionally the return array.  We define two variables for each
array parameter, one which represents an arbitrary sequence object, and one
which represents a PyArrayObject which contains a conversion of the sequence.
If the sequence object was already a well-behaved numarray, it is returned
without making a copy.

\begin{verbatim}
        /* Align, Byteswap, Contiguous, Typeconvert */
        kernel  = NA_InputArray(okernel, tFloat64, NUM_C_ARRAY);
        data    = NA_InputArray(odata, tFloat64, NUM_C_ARRAY);
        convolved = NA_OptionalOutputArray(oconvolved, tFloat64, NUM_C_ARRAY, data);

        if (!kernel || !data || !convolved) {
                PyErr_Format( _convolveError, 
                             "Convolve1d: error converting array inputs.");
                goto _fail;
        }
\end{verbatim}

These calls to NA_InputArray and OptionalOutputArray require that the arrays be
aligned, contiguous, and not byteswapped, and of type Float64, or a temporary
will be created.  If the user hasn't provided a output array we ask
\cfunction{NA_OptionalOutputArray} to create a copy of the input \var{data}.
We also check that the array screening and conversion process succeeded by
verifying that none of the array pointers is NULL.

\begin{verbatim}
        if ((kernel->nd != 1) || (data->nd != 1)) {
                PyErr_Format(_convolveError,
                      "Convolve1d: arrays must have 1 dimension.");
                goto _fail;
        }

        if (!NA_ShapeEqual(data, convolved)) {
                PyErr_Format(_convolveError,
                "Convolve1d: data and output arrays need identitcal shapes.");
                goto _fail;
        }
\end{verbatim}

Make sure we were passed one-dimensional arrays, and data and output have the
same size.

\begin{verbatim}
        Convolve1d(kernel->dimensions[0], NA_OFFSETDATA(kernel),
                   data->dimensions[0],   NA_OFFSETDATA(data),
                   NA_OFFSETDATA(convolved));
\end{verbatim}

Call the C function actually performing the work.  NA_OFFSETDATA returns the
pointer to the first element of the array,  adjusting for any byteoffset.

\begin{verbatim}
        Py_XDECREF(kernel);
        Py_XDECREF(data);
\end{verbatim}

Decrease the reference counters of the input arrays.  These were increased by
\cfunction{NA_InputArray}.  Py_XDECREF tolerates NULL.  DECREF'ing the
PyArrayObject is how temporaries are released and in the case of
IO and Output arrays, copied back onto the original.

\begin{verbatim}
        /* Align, Byteswap, Contiguous, Typeconvert */
        return NA_ReturnOutput(oconvolved, convolved);
_fail:
        Py_XDECREF(kernel);
        Py_XDECREF(data);
        Py_XDECREF(convolved);
        return NULL;
}
\end{verbatim}

Now return the results, which are either stored in the user-supplied array
\var{oconvolved} and \constant{Py_None} is returned, or if the user didn't
supply an output array the temporary \var{convolved} is returned.

If your C function creates the output array you can use the following sequence
to pass this array back to \python{}:

\begin{verbatim}
        double *result;
        int m, n;
        .
        .
        .
        result = func(...);
        if(NULL == result)
            return NULL;
        return NA_NewArray((void *)result, tFloat64, 2, m, n);
}
\end{verbatim}

The C function \cfunction{func} returns a newly allocated (m, n) array in
\var{result}.  After we check that everything is ok, we create a new numarray
using \cfunction{NA_NewArray} and pass it back to \python.  \cfunction{NA_NewArray}
creates a \class{numarray} with \constant{NUM_C_ARRAY} properties.  If you wish to
create an array that is byte-swapped, or misaligned, you can use
\cfunction{NA_NewAll}.

The C-code of the core convolution function is uninteresting.  The main point
of the example is that when using the high-level API, numarray specific code is
confined to the wrapper function.  The interface for the core function can be
written in terms of primitive numarray/C data items, not objects.  This is
possible because the high level API can be used to deliver C arrays.

\begin{verbatim}
static void Convolve1d(long ksizex, Float64 *kernel, 
     long dsizex, Float64*data, Float64 *convolved) 
{ 
  long xc; long halfk = ksizex/2;

  for(xc=0; xc<halfk; xc++)
      convolved[xc] = data[xc];
  
  for(xc=halfk; xc<dsizex-halfk; xc++) {
      long xk;
      double temp = 0;
      for (xk=0; xk<ksizex; xk++)
         temp += kernel[xk]*data[xc-halfk+xk];
      convolved[xc] = temp;
  }
  
  for(xc=dsizex-halfk; xc<dsizex; xc++)
     convolved[xc] = data[xc];
}
\end{verbatim}

\section{Element-wise API}
\label{sec:C-API:element-wise-api}

The element-wise in-place API is a family of macros and functions designed to
get and set elements of arrays which might be byteswapped, misaligned,
discontiguous, or of a different type.  You can obtain \class{PyArrayObject}s
for these misbehaved arrays from the high-level API by specifying fewer
requirements (perhaps just 0, rather than NUM_C_ARRAY).  In this way, you can
avoid the creation of temporaries at a cost of accessing your array with these
macros and functions and a significant performance penalty.  Make no mistake,
if you have the memory, the high level API is the fastest.  The whole point of
this API is to support cases where the creation of temporaries exhausts either
the physical or virtual address space.  Exhausting physical memory will result
in thrashing, while exhausting the virtual address space will result in program
exception and failure.  This API supports avoiding the creation of the
temporaries, and thus avoids exhausting physical and virual memory, possibly
improving net performance or even enabling program success where simpler
methods would just fail.

\subsection{Element-wise functions}
\label{sec:C-API:element-wise:functions}

The single element macros each access one element of an array at a time, and
specify the array type in two places: as part of the PyArrayObject type
descriptor, and as ``type''.  The former defines what the array is, and the
latter is required to produce correct code from the macro.  They should
\emph{match}.  When you pass ``type'' into one of these macros, you are
defining the kind of array the code can operate on.  It is an error to pass a
non-matching array to one of these macros.  One last piece of advice: call
these macros carefully, because the resulting expansions and error messages are
a *obscene*.  Note: the type parameter for a macro is one of the Numarray
Numeric Data Types, not a NumarrayType enumeration value.

\subsubsection{Pointer based single element macros}
\label{sec:C-API:pointer-based-single}

\begin{cfuncdesc}{}{NA_GETPa}{PyArrayObject*, type, char*}
   aligning
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GETPb}{PyArrayObject*, type, char*}
   byteswapping
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GETPf}{PyArrayObject*, type, char*}
   fast (well-behaved)
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GETP}{PyArrayObject*,  type, char*}
   testing: any of above
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SETPa}{PyArrayObject*, type, char*, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SETPb}{PyArrayObject*, type, char*, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SETPf}{PyArrayObject*, type, char*, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SETP}{PyArrayObject*,  type, char*, v}
\end{cfuncdesc}

\subsubsection{One index single element macros}
\begin{cfuncdesc}{}{NA_GET1a}{PyArrayObject*, type, i}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET1b}{PyArrayObject*, type, i}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET1f}{PyArrayObject*, type, i}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET1}{PyArrayObject*,  type, i}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET1a}{PyArrayObject*, type, i, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET1b}{PyArrayObject*, type, i, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET1f}{PyArrayObject*, type, i, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET1}{PyArrayObject*,  type, i, v}
\end{cfuncdesc}

\subsubsection{Two index single element macros}
\begin{cfuncdesc}{}{NA_GET2a}{PyArrayObject*, type, i, j}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET2b}{PyArrayObject*, type, i, j}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET2f}{PyArrayObject*, type, i, j}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_GET2}{PyArrayObject*,  type, i, j}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET2a}{PyArrayObject*, type, i, j, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET2b}{PyArrayObject*, type, i, j, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET2f}{PyArrayObject*, type, i, j, v}
\end{cfuncdesc}
\begin{cfuncdesc}{}{NA_SET2}{PyArrayObject*,  type, i, j, v}
\end{cfuncdesc}

\subsubsection{One and Two Index, Offset, Float64/Complex64/Int64 functions}

The \class{Int64}/\class{Float64}/\class{Complex64} functions require a
function call to access a single element of an array, making them slower than
the single element macros.  They have two advantages:
\begin{enumerate}
\item They're function calls, so they're a little more robust. 
\item They can handle \emph{any} input array type and behavior properties.
\end{enumerate}


While these functions have no error return status, they *can* alter the Python
error state, so well written extensions should call
\cfunction{PyErr_Occurred()} to determine if an error occurred and report it.
It's reasonable to do this check once at the end of an extension function,
rather than on a per-element basis.


\begin{cfuncdesc}{}{void NA_get_offset}{PyArrayObject *, int N, ...}
  \cfunction{NA_get_offset} computes the offset into an array object given a
  variable number of indices.  It is not especially robust, and it is
  considered an error to pass it more indices than the array has, or indices
  which are negative or out of range.
\end{cfuncdesc}

\begin{cfuncdesc}{Float64}{NA_get_Float64}{PyArrayObject *, long offset}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set_Float64}{PyArrayObject *, long offset, Float64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Float64}{NA_get1_Float64}{PyArrayObject *, int i}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set1_Float64}{PyArrayObject *, int i, Float64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Float64}{NA_get2_Float64}{PyArrayObject *, int i, int j}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set2_Float64}{PyArrayObject *, int i, int j, Float64 v}
\end{cfuncdesc}

\begin{cfuncdesc}{Int64}{NA_get_Int64}{PyArrayObject *, long offset}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set_Int64}{PyArrayObject *, long offset, Int64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Int64}{NA_get1_Int64}{PyArrayObject *, int i}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set1_Int64}{PyArrayObject *, int i, Int64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Int64}{NA_get2_Int64}{PyArrayObject *, int i, int j}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set2_Int64}{PyArrayObject *, int i, int j, Int64 v}
\end{cfuncdesc}

\begin{cfuncdesc}{Complex64}{NA_get_Complex64}{PyArrayObject *, long offset}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set_Complex64}{PyArrayObject *, long offset, Complex64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Complex64}{NA_get1_Complex64}{PyArrayObject *, int i}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set1_Complex64}{PyArrayObject *, int i, Complex64 v}
\end{cfuncdesc}
\begin{cfuncdesc}{Complex64}{NA_get2_Complex64}{PyArrayObject *, int i, int j}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{NA_set2_Complex64}{PyArrayObject *, int i, int j, Complex64 v}
\end{cfuncdesc}

\subsection{Example}
\label{sec:C-API:element-wise:example}

The \cfunction{convolve1D} wrapper function corresponding to section
\ref{sec:C-API:high-level:example} using the element-wise API could look
like:\footnote{This function is also available as an example in the source
   distribution.}

\begin{verbatim}
static PyObject *
Py_Convolve1d(PyObject *obj, PyObject *args)
{
        PyObject   *okernel, *odata, *oconvolved=Py_None;
        PyArrayObject *kernel, *data, *convolved;

        if (!PyArg_ParseTuple(args, "OO|O", &okernel, &odata, &oconvolved)) {
                PyErr_Format(_Error, "Convolve1d: Invalid parameters.");
                goto _fail;
        }

        kernel = NA_InputArray(okernel, tAny, 0);
        data   = NA_InputArray(odata, tAny, 0);
\end{verbatim}

For the kernel and data arrays, \class{numarray}s of any type are accepted
without conversion.  Thus there is no copy of the data made except for lists or
tuples.  All types, byteswapping, misalignment, and discontiguity must be
handled by Convolve1d.  This can be done easily using the get/set functions.
Macros, while faster than the functions, can only handle a single type.

\begin{verbatim}
        convolved = NA_OptionalOutputArray(oconvolved, tFloat64, 0, data);
\end{verbatim}

Also for the output array we accept any variety of type tFloat without
conversion.  No copy is made except for non-tFloat.  Non-numarray sequences are
not permitted as output arrays.  Byteswaping, misaligment, and discontiguity
must be handled by Convolve1d.  If the \python caller did not specify the
oconvolved array, it initially retains the value Py_None.  In that case,
\var{convolved} is cloned from the array \var{data} using the specified type.
It is important to clone from \var{data} and not \var{odata}, since the latter
may be an ordinary \python sequence which was converted into numarray
\var{data}.  

\begin{verbatim}
        if (!kernel || !data || !convolved)
                goto _fail;

        if ((kernel->nd != 1) || (data->nd != 1)) {
                PyErr_Format(_Error,
                     "Convolve1d: arrays must have exactly 1 dimension.");
                goto _fail;
        }

        if (!NA_ShapeEqual(data, convolved)) {
                PyErr_Format(_Error,
                    "Convolve1d: data and output arrays must have identical length.");
                goto _fail;
        }
        if (!NA_ShapeLessThan(kernel, data)) {
                PyErr_Format(_Error,
                    "Convolve1d: kernel must be smaller than data in both dimensions");
                goto _fail;
        }
        
        if (Convolve1d(kernel, data, convolved) < 0)  /* Error? */
            goto _fail;
        else {
           Py_XDECREF(kernel);
           Py_XDECREF(data);
           return NA_ReturnOutput(oconvolved, convolved);
        }
_fail:
        Py_XDECREF(kernel);
        Py_XDECREF(data);
        Py_XDECREF(convolved);
        return NULL;
}

\end{verbatim}

This function is very similar to the high-level API wrapper, the notable
difference is that we ask for the unconverted arrays \var{kernel} and
\var{data} and \var{convolved}.  This requires some attention in their usage.
The function that does the actual convolution in the example has to use
\cfunction{NA_get*} to read and \cfunction{NA_set*} to set an element of these
arrays, instead of using straight array notation.  These functions perform any
necessary type conversion, byteswapping, and alignment.

\begin{verbatim}
static int
Convolve1d(PyArrayObject *kernel, PyArrayObject *data, PyArrayObject *convolved)
{
        int xc, xk;
        int ksizex = kernel->dimensions[0];
        int halfk = ksizex / 2;
        int dsizex = data->dimensions[0];

        for(xc=0; xc<halfk; xc++)
                NA_set1_Float64(convolved, xc, NA_get1_Float64(data, xc));
                     
        for(xc=dsizex-halfk; xc<dsizex; xc++)
                NA_set1_Float64(convolved, xc, NA_get1_Float64(data, xc));

        for(xc=halfk; xc<dsizex-halfk; xc++) {
                Float64 temp = 0;
                for (xk=0; xk<ksizex; xk++) {
                        int i = xc - halfk + xk;
                        temp += NA_get1_Float64(kernel, xk) * 
                                NA_get1_Float64(data, i);
                }
                NA_set1_Float64(convolved, xc, temp);
        }
        if (PyErr_Occurred())
           return -1;
        else 
           return 0;
}
\end{verbatim}

\section{One-dimensional API}
\label{sec:C-API:One-dimensional-api}

The 1D in-place API is a set of functions for getting/setting elements from the
innermost dimension of an array.  These functions improve speed by moving type
switches, ``behavior tests'', and function calls out of the per-element loop.
The functions get/set a series of consequtive array elements to/from arrays of
\class{Int64}, \class{Float64}, or \class{Complex64}.  These functions are
(even) more intrusive than the single element functions, but have better
performance in many cases.  They can operate on arrays of any type, with the
exception of the Complex64 functions, which only handle Complex64.  The
functions return 0 on success and -1 on failure, with the Python error state
already set.  To be used profitably, the 1D API requires either a large single
dimension which can be processeed in blocks or a multi-dimensional array such
as an image.  In the latter case, the 1D API is suitable for processing one (or
more) scanlines at a time rather than the entire image at once.  See the source
distribution Examples/convolve/one_dimensionalmodule.c for an example of usage.

\begin{cfuncdesc}{long}{NA_get_offset}{PyArrayObject *, int N, ...}
   This function applies a (variable length) set of \var{N} indices to an array
   and returns a byte offset into the array.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_get1D_Int64}{%
      PyArrayObject *, long offset, int cnt, Int64 *out}%
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_set1D_Int64}{%
      PyArrayObject *, long offset, int cnt, Int64 *in}%
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_get1D_Float64}{%
      PyArrayObject *, long offset, int cnt, Float64 *out}%
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_set1D_Float64}{%
      PyArrayObject *, long offset, int cnt, Float64 *in}%
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_get1D_Complex64}{%
      PyArrayObject *, long offset, int cnt, Complex64 *out}%
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_set1D_Complex64}{%
      PyArrayObject *, long offset, int cnt, Complex64 *in}%
\end{cfuncdesc}

\section{Numeric emulation API}
\label{sec:C-API:numeric-emulation}

These notes describe the Numeric compatability functions which enable numarray
to utilize a subset of the extensions written for Numeric (NumPy).  Not all
Numeric C-API features and therefore not all Numeric extensions are currently
supported.  Users should be able to utilize suitable extensions written for
Numeric within the numarray environment by:

\begin{enumerate}
\item Writing a numarray setup.py file.
\item Scanning the extension C-code for all instances of array creation and
  return and making corrections as needed and specified below. 
\item Re-compiling the Numeric C-extension for numarray.
\end{enumerate}

Numarray's compatability with Numeric consists of 3 things:
\begin{enumerate}
\item A replacement header file, "arrayobject.h" which supplies emulation
   functions and macros for numarray just as the original arrayobject.h
   supplies the C-API for Numeric.
\item Layout and naming of the fundamental numarray C-type,
\ctype{PyArrayObject}, in Numeric compatible way.
\item A set of "emulation" functions.  These functions have the same names and
   parameters as the original Numeric functions, but operate on numarrays.  The
   emulation functions are also incomplete; features not currently supported
   should result in compile time warnings.
\end{enumerate}

\ctype{PyArrayObject} was discussed in an earlier section.  The header file,
``arrayobject.h'' is now fairly minimal, mainly just including libnumarray.h,
so needs little discussion.  The following section will discuss the Numeric
compatible functions.

\subsection{Emulation Functions}
\label{sec:C-API:compat:emulation-functions}

The basic use of numarrays by Numeric extensions is achieved in the extension
function's wrapper code by:
\begin{enumerate}
\item Ensuring creation of array objects by calls to emulation functions.
\item DECREFing each array and/or calling PyArray_Return.
\end{enumerate}

Unlike prior versions of numarray, this version *does* support access to array
objects straight out of PyArg_ParseTuple.  This is a consequence of a change to
the underlying object model, where a class instance has been replaced by
PyArrayObject.  Nevertheless, the ``right'' way to access arrays is either via
the high level interface or via emulated Numeric factory functions.  That way,
access to other python sequences is supported as well.

The creation of array objects is illustrated by the following of wrapper code
for a 2D convolution function:

\begin{verbatim}
static PyObject *
Py_Convolve2d(PyObject *obj, PyObject *args)
{
        PyObject   *okernel, *odata, *oconvolved=Py_None;
        PyArrayObject *kernel, *data, *convolved;

        if (!PyArg_ParseTuple(args, "OO|O", &okernel, &odata, &oconvolved)) {
                return PyErr_Format(_Error, 
                                    "Convove2d: Invalid parameters.");  
                goto _fail;
        }
\end{verbatim}

The first step was simply to get object pointers to the numarray parameters to
the convolution function: okernel, odata, and oconvolved.  Oconvolved is an
optional output parameter, specified with a default value of Py_None which is
used when only 2 parameters are supplied at the python level.  Each of the
``o'' parameters should be thought of as an arbitrary sequence object, not
necessarily an array.

The next step is to call emulation functions which convert sequence objects
into PyArrayObjects.  In a Numeric extension, these calls map tuples and lists
onto Numeric arrays and assert their dimensionality as 2D.  The numarray
emulation functions first map tuples, lists, and misbehaved numarrays onto
well-behaved numarrays.  Thus, calls to the emulation factory functions
transparently use the numarray high level interface and provide visibility only
to aligned and non-byteswapped array objects.

\begin{verbatim}
        kernel = (PyArrayObject *) PyArray_ContiguousFromObject(
                okernel, tFloat64, 2, 2);
        data = (PyArrayObject *) PyArray_ContiguousFromObject(
                odata, tFloat64, 2, 2);

        if (!kernel || !data) goto _fail;
\end{verbatim}

Extra processing is required to handle the output array \var{convolved},
cloning it from \var{data} if it was not specified.  Code should be supplied,
but is not, to verify that convolved and data have the same shape.  

\begin{verbatim}
        if (convolved == Py_None)
                convolved = (PyArrayObject *) PyArray_FromDims(
                        data->nd, data->dimensions, tFloat64);
        else
                convolved = (PyArrayObject *) PyArray_ContiguousFromObject(
                        oconvolved, tFloat64, 2, 2);
        if (!convolved) goto _fail;
\end{verbatim}

After converting all of the input paramters into \ctype{PyArrayObject}s, the
actual convolution is performed by a seperate function.  This could just as
well be done inline:

\begin{verbatim}
        Convolve2d(kernel, data, convolved);
\end{verbatim}

After processing the arrays, they should be DECREF'ed or returned using
\cfunction{PyArray_Return}.  It is generally not possible to directly return a
numarray object using \cfunction{Py_BuildValue} because the shadowing of
mis-behaved arrays needs to be undone.  Calling \cfunction{PyArray_Return}
destroys any temporary and passes the numarray back to \python.

\begin{verbatim}
        Py_DECREF(kernel);
        Py_DECREF(data);
        if (convolved != Py_None) {
                Py_DECREF(convolved);
                Py_INCREF(Py_None);
                return Py_None;
        } else
                return PyArray_Return(convolved);
_fail:
        Py_XDECREF(kernel);
        Py_XDECREF(data);
        Py_XDECREF(convolved);
        return NULL;
}
\end{verbatim}

Byteswapped or misaligned arrays are handled by a process of shadowing which
works like this:
\begin{enumerate}
\item When a "misbehaved" numarray is accessed via the Numeric emulation
  functions, first a well-behaved temporary copy (shadow) is created by
  NA_IoArray.
\item Operations performed by the extension function modifiy the data buffer
  belonging to the shadow.
\item On extension function exit, the shadow array is copied back onto the 
  original and the shadow is freed.
\end{enumerate}
All of this is transparent to the user; if the original array is well-behaved,
it works much like it always did; if not, what would have failed altogether
works at the cost of extra temporary storage.  Users which cannot afford the
cost of shadowing need to use numarray's native elementwise or 1D APIs.

\subsection{Numeric Compatible Functions}
\label{sec:C-API:compat:implemented-functions}

The following functions are currently implemented:
\begin{cfuncdesc}{PyArrayObject*}{PyArray_FromDims}{int nd, int *dims, int type}
   This function will allocate a new numarray.

   An array created with PyArray_FromDims can be used as a temporary or
   returned using PyArray_Return.
   
   Used as a temporary, calling Py_DECREF deallocates it.   
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_FromDimsAndData}{int nd, int *dims, int type, char *data}
   This function will allocate a numarray of the specified shape and type, and
   it's contents will be copied from the specified data pointer.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_ContiguousFromObject}{%
      PyObject *op, int type, int min_dim, int max_dim}%
   Returns an emulation object for a contiguous numarray of 'type' created from
   the sequence object 'op'.  If 'op' is a contiguous, aligned, non-byteswapped
   numarray, then the emulation object refers to it directly.  Otherwise a
   well-behaved numarray will be created from 'op' and the emulation object
   will refer to it.  min_dim and max_dim bound the expected rank as in
   Numeric.  \code{min_dim==max_dim} specifies an exact rank.
   \code{min_dim==max_dim==0} specifies \emph{any} rank.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_CopyFromObject}{%
      PyObject *op, int type, int min_dim, int max_dim}%
   Returns a contiguous array, similar to PyArray_FromContiguousObject, but
   always returning an emulation object referring to a new numarray copied from
   the original sequence.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_FromObject}{%
      PyObject  *op, int type, int min_dim, int max_dim}%
   Returns and emulation object based on 'op', possibly discontiguous.  The
   strides array must be used to access elements of the emulation object.
   
   If 'op' is a byteswapped or misaligned numarray, FromObject creates a
   temporary copy and the emulation object refers to it.
   
   If 'op' is a nonswapped, aligned numarray, the emulation object refers to
   it.
   
   If 'op' is some other sequence, it is converted to a numarray and the
   emulation object refers to that.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_Return}{PyArrayObject *apr}
   Returns emulation object 'apr' to python.  The emulation object itself is
   destructed.  The numarray it refers to (base) is returned as the result of
   the function.
   
   An additional check is (or eventually will be) performed to guarantee that
   rank-0 arrays are converted to appropriate python scalars.
   
   PyArray_Return has no net effect on the reference count of the underlying
   numarray.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_As1D}{PyObject **op, char **ptr, int *d1, int typecode}
   Copied from Numeric verbatim.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_As2D}{PyObject **op, char ***ptr, int *d1, int *d2, int typecode}
   Copied from Numeric verbatim.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_Free}{PyObject *op, char *ptr}
   Copied from Numeric verbatim. \note{This means including bugs and all!}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_Check}{PyObject *op}
   This function returns 1 if op is a PyArrayObject.  
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_Size}{PyObject *op}
   This function returns the total element count of the array.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_NBYTES}{PyArrayObject *op}
   This function returns the total size in bytes of the array, and assumes that
bytestride == itemsize, so that the size is product(shape)*itemsize.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyArray_Copy}{PyArrayObject *op}
   This function returns a copy of the array 'op'.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_CanCastSafely}{PyArrayObject *op, int type}
  This function returns 1 IFF the array 'op' can be safely cast to 'type',
otherwise it returns 0.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArrayObject*}{PyArray_Cast}{PyArrayObject *op, int type}
  This function casts the array 'op' into an equivalent array of type 'type'.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArray_Descr*}{PyArray_DescrFromType}{int type}
This function returns a pointer to the array descriptor for 'type'.  The
numarray version of PyArray_Descr is incomplete and does not support casting,
getitem, setitem, one, or zero.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArray_isArray(PyObject *o)}
  This macro is designed to fail safe and return 0 when numarray is not
  installed at all.  When numarray is installed, it returns 1 iff object 'o' is
  a numarray, and 0 otherwise.  This macro facilitates the optional use of
  numarray within an extension.
\end{cfuncdesc}

\subsection{Unsupported Numeric Features}
\label{sec:C-API:compat:unsupported}

\begin{itemize}
\item PyArrayError 
\item PyArray_ObjectType() 
\item PyArray_Reshape()
\item PyArray_SetStringFunction() 
\item PyArray_SetNumericOps() 
\item PyArray_Take()
\item UFunc API
\end{itemize}

\section{New numarray functions}
\label{sec:C-API:new-numarray-functions}

There are several functions to create \class{numarray}s at the C level:

\begin{cfuncdesc}{static PyObject*}{NA_NewArray}{%
      void *buffer, NumarrayType type, int ndim, ...}%
    Create a new \class{numarray} from C data \var{buffer}.  The new array has
    type \var{type}, \var{ndim} dimensions, and the length of each dimension
    must be given as the remaining (variable length) list of int parameters. 
    Data is copied from buffer into the memory object of the new array.
\end{cfuncdesc}

\begin{cfuncdesc}{static PyObject*}{NA_vNewArray}{%
      void *buffer, NumarrayType type, int ndim, maybelong *shape}%
    Create a new \class{numarray} from C data \var{buffer}.  The new array has
    type \var{type}, \var{ndim} dimensions, and the length of each dimension
    must be given as an array of long pointed to by \var{shape}. Data is copied
    from buffer into the memory object of the new array.
\end{cfuncdesc}

\begin{cfuncdesc}{static PyObject*}{NA_NewAll}{%
    int ndim, maybelong *shape, NumarrayType type, void *buffer, 
    maybelong byteoffset, maybelong bytestride, int byteorder, int aligned, 
    int writable}% Create a new
    \class{numarray} from C data \var{buffer}.  The new array has type
    \var{type}, \var{ndim} dimensions, and the length of each dimensions must
    be given in \var{shape[ndim]}.  \var{byteoffset}, \var{bytestride} specify
    the data-positions in the C array to use. \var{byteorder} and \var{aligned}
    specify the corresponding parameters.  \var{byteorder} takes one of the
    values \constant{NUM_BIG_ENDIAN} or \constant{NUM_LITTLE_ENDIAN}.
    \var{writable} defines whether the buffer object associated with the
    resuling array is readonly or writable.  Data is copied from buffer into
    the memory object of the new array.
\end{cfuncdesc}

\begin{cfuncdesc}{static PyObject*}{NA_NewAllStrides}{%
    int ndim, maybelong *shape, maybelong *strides, NumarrayType type, 
    void *buffer, maybelong byteoffset, maybelong byteorder, int aligned, 
    int writable}% Create a new
  \class{numarray} from C data \var{buffer}.  The new array has type
  \var{type}, \var{ndim} dimensions, and the length of each dimensions must be
  given in \var{shape[ndim]}.  The byte offset between successive indices of a
  dimension is specified by \var{strides[ndim]}.  \var{byteoffset} specifies
  the offset from the base of the buffer to the zeroth element of the array.
  \var{byteorder} and \var{aligned} specify the corresponding parameters.
  \var{byteorder} takes one of the values \constant{NUM_BIG_ENDIAN} or
  \constant{NUM_LITTLE_ENDIAN}.  \var{writable} defines whether the buffer
  object associated with the resuling array is readonly or writable.  Data is
  copied from buffer into the memory object of the new array.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_ShapeEqual}{PyArrayObject*a,PyArrayObject*b}
This function compares the shapes of two arrays, and returns 1 if they
are the same, 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_ShapeLessThan}{PyArrayObject*a,PyArrayObject*b}
This function compares the shapes of two arrays, and returns 1 if each
dimension of 'a' is less than the corresponding dimension of 'b', 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_ByteOrder}{}
This function returns the system byte order, either NUM_LITTLE_ENDIAN or
NUM_BIG_ENDIAN.
\end{cfuncdesc}

\begin{cfuncdesc}{Bool}{NA_IeeeSpecial32}{Float32 *f, Int32 *mask}
This function returns 1 IFF Float32 value '*f' matches any of the IEEE special
value criteria specified by '*mask'.  See ieeespecial.h for the mask bit values
which can be or'ed together to specify mask.
\end{cfuncdesc}

\begin{cfuncdesc}{Bool}{NA_IeeeSpecial64}{Float64*,Int32*}
This function returns 1 IFF Float64 value '*f' matches any of the IEEE special
value criteria specified by '*mask'.  See ieeespecial.h for the mask bit values
which can be or'ed together to specify mask.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArrayObject *}{NA_updateDataPtr}{PyArrayObject *}
This function updates the values derived from the ``_data'' buffer, namely the
data pointer and buffer WRITABLE flag bit.  This needs to be called upon
entering or re-entering C-code from Python, since it is possible for buffer
objects to move their data buffers as a result of executing arbitrary Python
and hence arbitrary C-code.  
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{NA_typeNoToName}{int}
NA_typeNoToName translates a NumarrayType into a character string which can be
used to display it:  e.g.  tInt32 converts to the string ``Int32''
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{NA_typeNoToTypeObject}{int}
This function converts a NumarrayType C type code into the NumericType object
which implements and represents it more fully.  tInt32 converts to the type
object numarray.Int32.  
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_typeObjectToTypeNo}{PyObject*}
This function converts a numarray type object (e.g. numarray.Int32) into the
corresponding NumarrayType (e.g. tInt32) C type code. 
\end{cfuncdesc}

\begin{cfuncdesc} {PyObject*}{NA_intTupleFromMaybeLongs}{int,maybelong*}
This function creates a tuple of Python ints from an array of C maybelong integers.
\end{cfuncdesc}

\begin{cfuncdesc}{long}{NA_maybeLongsFromIntTuple}{int,maybelong*,PyObject*}
This function fills an array of C long integers with the converted values from
a tuple of Python ints.  It returns the number of conversions, or -1 for error.
\end{cfuncdesc}

\begin{cfuncdesc}{long}{NA_isIntegerSequence}{PyObject*}
This function returns 1 iff the single parameter is a sequence of Python
integers, and 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{NA_setArrayFromSequence}{PyArrayObject*,PyObject*}
This function copies the elementwise from a sequence object to a numarray.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_maxType}{PyObject*}
This function returns an integer code corresponding to the highest kind of
Python numeric object in a sequence.  INT(0) LONG(1) FLOAT(2) COMPLEX(3).
On error -1 is returned.
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{NA_getPythonScalar}{PyArrayObject *a, long offset}
This function returns the Python object corresponding to the single element of 
the array 'a' at the given byte offset.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_setFromPythonScalar}{PyArrayObject *a, long offset, PyObject*value}
This function sets the single element of the array 'a' at the given byte
offset to 'value'.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_NDArrayCheck}{PyObject*o}
This function returns 1 iff the 'o' is an instance of NDArray or an instance of
a subclass of NDArray, and 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_NumArrayCheck}{PyObject*}
This function returns 1 iff the 'o' is an instance of NumArray or an instance of
a subclass of NumArray, and 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_ComplexArrayCheck}{PyObject*}
This function returns 1 iff the 'o' is an instance of ComplexArray or an instance of
a subclass of ComplexArray, and 0 otherwise.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_elements}{PyArrayObject*}
This function returns the total count of elements in an array,  essentially the
product of the elements of the array's shape.
\end{cfuncdesc}

\begin{cfuncdesc}{PyArrayObject *}{NA_copy}{PyArrayObject*}
This function returns a copy of the given array.
\end{cfuncdesc}

\begin{cfuncdesc}{int}{NA_copyArray}{PyArrayObject*to, const PyArrayObject *from}
This function returns a copies one array onto another;  used in f2py.
\end{cfuncdesc}

%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End:
