Merge pull request #155 from PyO3/npyiter-mentoring

Complete Iterator API

Author: kngwyu

src/array.rs

@@ -175,7 +175,7 @@ impl<T, D> PyArray<T, D> {
     /// use pyo3::types::IntoPyDict;
     /// let gil = pyo3::Python::acquire_gil();
     /// let py = gil.python();
-    /// let array = numpy::PyArray::arange(py, 0, 1, 10);
+    /// let array = numpy::PyArray::arange(py, 0, 10, 1);
     /// assert!(array.is_contiguous());
     /// let locals = [("np", numpy::get_array_module(py).unwrap())].into_py_dict(py);
     /// let not_contiguous: &numpy::PyArray1<f32> = py
@@ -773,6 +773,14 @@ impl<T: Element> PyArray<T, Ix1> {
         self.resize_([new_elems], 1, NPY_ORDER::NPY_ANYORDER)
     }
 
+    /// Iterates all elements of this array.
+    /// See [NpySingleIter](../npyiter/struct.NpySingleIter.html) for more.
+    pub fn iter<'py>(
+        &'py self,
+    ) -> PyResult<crate::NpySingleIter<'py, T, crate::npyiter::ReadWrite>> {
+        crate::NpySingleIterBuilder::readwrite(self).build()
+    }
+
     fn resize_<D: IntoDimension>(
         &self,
         dims: D,

src/lib.rs

@@ -40,6 +40,7 @@ pub mod array;
 pub mod convert;
 mod error;
 pub mod npyffi;
+pub mod npyiter;
 mod readonly;
 mod slice_box;
 mod types;
@@ -51,6 +52,9 @@ pub use crate::array::{
 pub use crate::convert::{IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 pub use crate::error::{FromVecError, NotContiguousError, ShapeError};
 pub use crate::npyffi::{PY_ARRAY_API, PY_UFUNC_API};
+pub use crate::npyiter::{
+    IterMode, NpyIterFlag, NpyMultiIter, NpyMultiIterBuilder, NpySingleIter, NpySingleIterBuilder,
+};
 pub use crate::readonly::{
     PyReadonlyArray, PyReadonlyArray1, PyReadonlyArray2, PyReadonlyArray3, PyReadonlyArray4,
     PyReadonlyArray5, PyReadonlyArray6, PyReadonlyArrayDyn,

src/npyffi/flags.rs

@@ -1,3 +1,4 @@
+use super::npy_uint32;
 use std::os::raw::c_int;
 
 pub const NPY_ARRAY_C_CONTIGUOUS: c_int = 0x0001;
@@ -28,3 +29,36 @@ pub const NPY_ARRAY_OUT_FARRAY: c_int = NPY_ARRAY_FARRAY;
 pub const NPY_ARRAY_INOUT_FARRAY: c_int = NPY_ARRAY_FARRAY | NPY_ARRAY_UPDATEIFCOPY;
 pub const NPY_ARRAY_INOUT_FARRAY2: c_int = NPY_ARRAY_FARRAY | NPY_ARRAY_WRITEBACKIFCOPY;
 pub const NPY_ARRAY_UPDATE_ALL: c_int = NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS;
+
+pub const NPY_ITER_C_INDEX: npy_uint32 = 0x00000001;
+pub const NPY_ITER_F_INDEX: npy_uint32 = 0x00000002;
+pub const NPY_ITER_MULTI_INDEX: npy_uint32 = 0x00000004;
+pub const NPY_ITER_EXTERNAL_LOOP: npy_uint32 = 0x00000008;
+pub const NPY_ITER_COMMON_DTYPE: npy_uint32 = 0x00000010;
+pub const NPY_ITER_REFS_OK: npy_uint32 = 0x00000020;
+pub const NPY_ITER_ZEROSIZE_OK: npy_uint32 = 0x00000040;
+pub const NPY_ITER_REDUCE_OK: npy_uint32 = 0x00000080;
+pub const NPY_ITER_RANGED: npy_uint32 = 0x00000100;
+pub const NPY_ITER_BUFFERED: npy_uint32 = 0x00000200;
+pub const NPY_ITER_GROWINNER: npy_uint32 = 0x00000400;
+pub const NPY_ITER_DELAY_BUFALLOC: npy_uint32 = 0x00000800;
+pub const NPY_ITER_DONT_NEGATE_STRIDES: npy_uint32 = 0x00001000;
+pub const NPY_ITER_COPY_IF_OVERLAP: npy_uint32 = 0x00002000;
+pub const NPY_ITER_READWRITE: npy_uint32 = 0x00010000;
+pub const NPY_ITER_READONLY: npy_uint32 = 0x00020000;
+pub const NPY_ITER_WRITEONLY: npy_uint32 = 0x00040000;
+pub const NPY_ITER_NBO: npy_uint32 = 0x00080000;
+pub const NPY_ITER_ALIGNED: npy_uint32 = 0x00100000;
+pub const NPY_ITER_CONTIG: npy_uint32 = 0x00200000;
+pub const NPY_ITER_COPY: npy_uint32 = 0x00400000;
+pub const NPY_ITER_UPDATEIFCOPY: npy_uint32 = 0x00800000;
+pub const NPY_ITER_ALLOCATE: npy_uint32 = 0x01000000;
+pub const NPY_ITER_NO_SUBTYPE: npy_uint32 = 0x02000000;
+pub const NPY_ITER_VIRTUAL: npy_uint32 = 0x04000000;
+pub const NPY_ITER_NO_BROADCAST: npy_uint32 = 0x08000000;
+pub const NPY_ITER_WRITEMASKED: npy_uint32 = 0x10000000;
+pub const NPY_ITER_ARRAYMASK: npy_uint32 = 0x20000000;
+pub const NPY_ITER_OVERLAP_ASSUME_ELEMENTWISE: npy_uint32 = 0x40000000;
+
+pub const NPY_ITER_GLOBAL_FLAGS: npy_uint32 = 0x0000ffff;
+pub const NPY_ITER_PER_OP_FLAGS: npy_uint32 = 0xffff0000;