<commit_before>Array Iterator API
==================

.. sectionauthor:: <NAME>

.. index::
   pair: iterator; C-API
   pair: C-API; iterator

.. versionadded:: 1.6

Array Iterator
--------------

The array iterator encapsulates many of the key features in ufuncs,
allowing user code to support features like output parameters,
preservation of memory layouts, and buffering of data with the wrong
alignment or type, without requiring difficult coding.

This page documents the API for the iterator.
The C-API naming convention chosen is based on the one in the numpy-refactor
branch, so will integrate naturally into the refactored code base.
The iterator is named ``NpyIter`` and functions are
named ``NpyIter_*``.

There is an :ref:`introductory guide to array iteration <arrays.nditer>`
which may be of interest for those using this C API. In many instances,
testing out ideas by creating the iterator in Python is a good idea
before writing the C iteration code.

Converting from Previous NumPy Iterators
----------------------------------------

The existing iterator API includes functions like PyArrayIter_Check,
PyArray_Iter* and PyArray_ITER_*.  The multi-iterator array includes
PyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest.  The
new iterator design replaces all of this functionality with a single object
and associated API.  One goal of the new API is that all uses of the
existing iterator should be replaceable with the new iterator without
significant effort. In 1.6, the major exception to this is the neighborhood
iterator, which does not have corresponding features in this iterator.

Here is a conversion table for which functions to use with the new iterator:

=====================================  =============================================
*Iterator Functions*
:cfunc:`PyArray_IterNew`               :cfunc:`NpyIter_New`
:cfunc:`PyArray_IterAllButAxis`        :cfunc:`NpyIter_New` + ``axes`` parameter **or**<commit_msg>DOC: iterator: don't bother users with NumPy development details<commit_after>Array Iterator API
==================

.. sectionauthor:: <NAME>

.. index::
   pair: iterator; C-API
   pair: C-API; iterator

.. versionadded:: 1.6

Array Iterator
--------------

The array iterator encapsulates many of the key features in ufuncs,
allowing user code to support features like output parameters,
preservation of memory layouts, and buffering of data with the wrong
alignment or type, without requiring difficult coding.

This page documents the API for the iterator.
The iterator is named ``NpyIter`` and functions are
named ``NpyIter_*``.

There is an :ref:`introductory guide to array iteration <arrays.nditer>`
which may be of interest for those using this C API. In many instances,
testing out ideas by creating the iterator in Python is a good idea
before writing the C iteration code.

Converting from Previous NumPy Iterators
----------------------------------------

The existing iterator API includes functions like PyArrayIter_Check,
PyArray_Iter* and PyArray_ITER_*.  The multi-iterator array includes
PyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest.  The
new iterator design replaces all of this functionality with a single object
and associated API.  One goal of the new API is that all uses of the
existing iterator should be replaceable with the new iterator without
significant effort. In 1.6, the major exception to this is the neighborhood
iterator, which does not have corresponding features in this iterator.

Here is a conversion table for which functions to use with the new iterator:

=====================================  =============================================
*Iterator Functions*
:cfunc:`PyArray_IterNew`               :cfunc:`NpyIter_New`
:cfunc:`PyArray_IterAllButAxis`        :cfunc:`NpyIter_New` + ``axes`` parameter **or**
{'fraction_non_alphanumeric': 0.13043478260869565, 'fraction_numerical': 0.002082790939859412, 'mean_word_length': 4.270233196159122, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5549698', 'n_tokens_mistral': 960, 'n_tokens_neox': 914, 'n_words': 472}