10. C extension API

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.

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 10.3.
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 10.4.
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 10.5.
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 10.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 10.7


Subsections
Send comments to the NumArray community.