This chapter describes the different available C-APIs for numarray
based extension modules.
While this chapter describes the numarray-specifics for writing
extension modules, a basic understanding of Pythonextension modules is
expected. See Python's Extending and
Embedding tutorial and the
Python/C API.
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 numarrays.
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.
Numeric compatability
This API provides a reasonable (if not complete)
simulation of the Numeric C-API. It is written in terms of the numarray
high level API (discussed below) so that misbehaved numarrays are copied
prior to processing with legacy Numeric code. This API was actually written
last because of the extra considerations in numarray not found in Numeric.
Nevertheless, it is perhaps the most important because it enables writing
extension modules which can be compiled for either numarray or Numeric. It
is also very useful for porting existing Numeric code. See section
14.3.
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
14.4.
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 relatively slow
compared to raw access to C data, and the functions even slower. See
section 14.5.
One-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 array rather than one test per
element. Fewer tests means better performance, but at a cost of some
temporary data and more difficult usage. See section
14.6.
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
14.7
