document array module

parent 8d073443
...@@ -20,13 +20,16 @@ Safe usage with memory views ...@@ -20,13 +20,16 @@ Safe usage with memory views
:: ::
from cpython cimport array as c_array from cpython cimport array
from array import array from array import array
cdef c_array.array a = array('i', [1, 2, 3]) cdef array.array a = array('i', [1, 2, 3])
cdef int[:] ca = a cdef int[:] ca = a
print ca[0] print ca[0]
NB: the import brings the regular Python array object into the namespace
while the cimport adds functions accessible from Cython.
A Python array is constructed with a type signature and sequence of A Python array is constructed with a type signature and sequence of
initial values. For the possible type signatures, refer to the Python initial values. For the possible type signatures, refer to the Python
documentation for the `array module <http://docs.python.org/library/array.html>`_. documentation for the `array module <http://docs.python.org/library/array.html>`_.
...@@ -36,9 +39,9 @@ memory view, there will be a slight overhead to construct the memory ...@@ -36,9 +39,9 @@ memory view, there will be a slight overhead to construct the memory
view. However, from that point on the variable can be passed to other view. However, from that point on the variable can be passed to other
functions without overhead, so long as it is typed:: functions without overhead, so long as it is typed::
from cpython cimport array as c_array from cpython cimport array
from array import array from array import array
cdef c_array.array a = array('i', [1, 2, 3]) cdef array.array a = array('i', [1, 2, 3])
cdef int[:] ca = a cdef int[:] ca = a
cdef int overhead(object a): cdef int overhead(object a):
...@@ -60,10 +63,10 @@ right type and signedness. ...@@ -60,10 +63,10 @@ right type and signedness.
:: ::
from cpython cimport array as c_array from cpython cimport array
from array import array from array import array
cdef c_array.array a = array('i', [1, 2, 3]) cdef array.array a = array('i', [1, 2, 3])
# access underlying pointer: # access underlying pointer:
print a.data.as_ints[0] print a.data.as_ints[0]
...@@ -71,6 +74,10 @@ right type and signedness. ...@@ -71,6 +74,10 @@ right type and signedness.
from libc.string cimport memset from libc.string cimport memset
memset(a.data.as_voidptr, 0, len(a) * sizeof(int)) memset(a.data.as_voidptr, 0, len(a) * sizeof(int))
Note that any length-changing operation on the array object may invalidate the
pointer.
Cloning, extending arrays Cloning, extending arrays
------------------------- -------------------------
To avoid having to use the array constructor from the Python module, To avoid having to use the array constructor from the Python module,
...@@ -80,14 +87,14 @@ zero when requested. ...@@ -80,14 +87,14 @@ zero when requested.
:: ::
from cpython cimport array as c_array from cpython cimport array, clone
from array import array from array import array
cdef c_array.array int_array_template = array('i', []) cdef array.array int_array_template = array('i', [])
cdef c_array.array newarray cdef array.array newarray
# create an array with 3 elements with same type as template # create an array with 3 elements with same type as template
newarray = c_array.clone(int_array_template, 3, zero=False) newarray = clone(int_array_template, 3, zero=False)
An array can also be extended and resized; this avoids repeated memory An array can also be extended and resized; this avoids repeated memory
reallocation which would occur if elements would be appended or removed reallocation which would occur if elements would be appended or removed
...@@ -95,13 +102,89 @@ one by one. ...@@ -95,13 +102,89 @@ one by one.
:: ::
from cpython cimport array as c_array from cpython cimport array
from array import array from array import array
cdef c_array.array a = array('i', [1, 2, 3]) cdef array.array a = array('i', [1, 2, 3])
cdef c_array.array b = array('i', [4, 5, 6]) cdef array.array b = array('i', [4, 5, 6])
# extend a with b, resize as needed # extend a with b, resize as needed
c_array.extend(a, b) array.extend(a, b)
# resize a, leaving just original three elements # resize a, leaving just original three elements
c_array.resize(a, len(a) - len(b)) a.resize(len(a) - len(b))
API reference
-------------
Data fields
~~~~~~~~~~~
::
data.as_voidptr
data.as_chars
data.as_schars
data.as_uchars
data.as_shorts
data.as_ushorts
data.as_ints
data.as_uints
data.as_longs
data.as_ulongs
data.as_floats
data.as_doubles
data.as_pyunicodes
Direct access to the underlying contiguous C array, with given type;
e.g., ``myarray.data.as_ints``.
Methods
~~~~~~~
The following methods are available on cdef'ed array objects::
int resize(array self, Py_ssize_t n) except -1
Fast resize / realloc. Not suitable for repeated, small increments; resizes
underlying array to exactly the requested amount.
::
int resize_smart(array self, Py_ssize_t n) except -1
Efficient for small increments (not available in Python 2.3 and lower); uses
growth pattern that delivers amortized linear-time appends.
Functions
~~~~~~~~~
The following functions are available to Cython from the array module::
cdef inline array clone(array template, Py_ssize_t length, bint zero)
Fast creation of a new array, given a template array. Type will be same as
``template``. If zero is ``True``, new array will be initialized with zeroes.
::
cdef inline array copy(array self)
Make a copy of an array.
::
cdef inline int extend_buffer(array self, char* stuff, Py_ssize_t n) except -1
Efficient appending of new data of same type (e.g. of same array type)
``n``: number of elements (not number of bytes!)
::
cdef inline int extend(array self, array other) except -1
Extend array with data from another array; types must match.
::
cdef inline void zero(array self)
Set all elements of array to zero.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment