DOC: Add some missing documentation, hyper-link the iterator documentation

1 files changed, 159 insertions, 18 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index a548144bc..c89d686c6 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -160,15 +160,18 @@ From scratch
 
 .. cfunction:: PyObject* PyArray_NewLikeArray(PyArrayObject* prototype, NPY_ORDER order, PyArray_Descr* descr)
 
+    .. versionadded:: 1.6
+
    This function steals a reference to *descr* if it is not NULL.
 
    This array creation routine allows for the convenient creation of
    a new array matching an existing array's shapes and memory layout,
    possibly changing the layout and/or data type.
 
-   When *order* is NPY_ANYORDER, the result order is NPY_FORTRANORDER if
-   *prototype* is a fortran array, NPY_CORDER otherwise.  When *order* is
-   NPY_KEEPORDER, the result order matches that of *prototype*, even
+   When *order* is :cdata:`NPY_ANYORDER`, the result order is
+   :cdata:`NPY_FORTRANORDER` if *prototype* is a fortran array,
+   :cdata:`NPY_CORDER` otherwise.  When *order* is
+   :cdata:`NPY_KEEPORDER`, the result order matches that of *prototype*, even
    when the axes of *prototype* aren't in C or Fortran order.
 
    If *descr* is NULL, the data type of *prototype* is used.
@@ -393,6 +396,68 @@ From other objects
         :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_WRITEABLE` \|
         :cdata:`NPY_ALIGNED` \| :cdata:`NPY_UPDATEIFCOPY`
 
+.. cfunction:: int PyArray_GetArrayParamsFromObject(PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, PyArray_Descr** out_dtype, int* out_ndim, npy_intp* out_dims, PyArrayObject** out_arr, PyObject* context)
+
+    .. versionadded:: 1.6
+
+    Retrieves the array parameters for viewing/converting an arbitrary
+    PyObject* to a NumPy array. This allows the "innate type and shape"
+    of Python list-of-lists to be discovered without
+    actually converting to an array. PyArray_FromAny calls this function
+    to analyze its input.
+
+    In some cases, such as structured arrays and the __array__ interface,
+    a data type needs to be used to make sense of the object.  When
+    this is needed, provide a Descr for 'requested_dtype', otherwise
+    provide NULL. This reference is not stolen. Also, if the requested
+    dtype doesn't modify the interpretation of the input, out_dtype will
+    still get the "innate" dtype of the object, not the dtype passed
+    in 'requested_dtype'.
+
+    If writing to the value in 'op' is desired, set the boolean
+    'writeable' to 1.  This raises an error when 'op' is a scalar, list
+    of lists, or other non-writeable 'op'. This differs from passing
+    NPY_WRITEABLE to PyArray_FromAny, where the writeable array may
+    be a copy of the input.
+
+    When success (0 return value) is returned, either out_arr
+    is filled with a non-NULL PyArrayObject and
+    the rest of the parameters are untouched, or out_arr is
+    filled with NULL, and the rest of the parameters are filled.
+
+    Typical usage:
+
+    .. code-block:: c
+
+        PyArrayObject *arr = NULL;
+        PyArray_Descr *dtype = NULL;
+        int ndim = 0;
+        npy_intp dims[NPY_MAXDIMS];
+
+        if (PyArray_GetArrayParamsFromObject(op, NULL, 1, &dtype,
+                                            &ndim, &dims, &arr, NULL) < 0) {
+            return NULL;
+        }
+        if (arr == NULL) {
+            ... validate/change dtype, validate flags, ndim, etc ...
+            // Could make custom strides here too
+            arr = PyArray_NewFromDescr(&PyArray_Type, dtype, ndim,
+                                        dims, NULL,
+                                        fortran ? NPY_F_CONTIGUOUS : 0,
+                                        NULL);
+            if (arr == NULL) {
+                return NULL;
+            }
+            if (PyArray_CopyObject(arr, op) < 0) {
+                Py_DECREF(arr);
+                return NULL;
+            }
+        }
+        else {
+            ... in this case the other parameters weren't filled, just
+                validate and possibly copy arr itself ...
+        }
+        ... use arr ...
 
 .. cfunction:: PyObject* PyArray_CheckFromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context)
 
@@ -869,16 +934,20 @@ Converting data types
 
 .. cfunction:: int PyArray_CanCastTypeTo(PyArray_Descr* fromtype, PyArray_Descr* totype, NPY_CASTING casting)
 
+    .. versionadded:: 1.6
+
     Returns non-zero if an array of data type *fromtype* (which can
     include flexible types) can be cast safely to an array of data
     type *totype* (which can include flexible types) according to
-    the casting rule *casting*. For simple types with NPY_SAFE_CASTING,
+    the casting rule *casting*. For simple types with :cdata:`NPY_SAFE_CASTING`,
     this is basically a wrapper around :cfunc:`PyArray_CanCastSafely`, but
     for flexible types such as strings or unicode, it produces results
     taking into account their sizes.
 
 .. cfunction:: int PyArray_CanCastArrayTo(PyArrayObject* arr, PyArray_Descr* totype, NPY_CASTING casting)
 
+    .. versionadded:: 1.6
+
     Returns non-zero if *arr* can be cast to *totype* according
     to the casting rule given in *casting*.  If *arr* is an array
     scalar, its value is taken into account, and non-zero is also
@@ -887,6 +956,8 @@ Converting data types
 
 .. cfunction:: PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)
 
+    .. versionadded:: 1.6
+
     If *arr* is an array, returns its data type descriptor, but if
     *arr* is an array scalar (has 0 dimensions), it finds the data type
     of smallest kind and size to which the value may be converted
@@ -894,11 +965,15 @@ Converting data types
 
 .. cfunction:: PyArray_Descr* PyArray_PromoteTypes(PyArray_Descr* type1, PyArray_Descr* type2)
 
+    .. versionadded:: 1.6
+
     Finds the data type of smallest size and kind to which *type1* and
     *type2* may be safely converted.
 
 .. cfunction:: PyArray_Descr* PyArray_ResultType(npy_intp narrs, PyArrayObject**arrs, npy_intp ndtypes, PyArray_Descr**dtypes)
 
+    .. versionadded:: 1.6
+
     This applies PyArray_PromoteTypes to all the inputs, along with
     using the NumPy rules for combining scalars and arrays, to
     determine the output type of a set of operands.  This is the
@@ -929,9 +1004,9 @@ Converting data types
 
 .. cfunction:: PyArrayObject** PyArray_ConvertToCommonType(PyObject* op, int* n)
 
-    May be deprecated in the future.  Using the newly introduced iterator
-    with flag NPY_ITER_COMMON_DTYPE or with the same dtype parameter for
-    all operands is preferred to this method.
+    May be deprecated in the future.  Using the newly introduced
+    :ctype:`NpyIter` with flag :cdata:`NPY_ITER_COMMON_DTYPE` or with
+    the same dtype parameter for all operands is preferred to this method.
 
     Convert a sequence of Python objects contained in *op* to an array
     of ndarrays each having the same data type. The type is selected
@@ -1596,6 +1671,8 @@ Item selection and manipulation
 
 .. cfunction:: npy_intp PyArray_CountNonzero(PyArrayObject* self)
 
+    .. versionadded:: 1.6
+
     Counts the number of non-zero elements in the array object *self*.
 
 .. cfunction:: PyObject* PyArray_Nonzero(PyArrayObject* self)
@@ -1813,7 +1890,7 @@ Array Functions
     second-to-last dimension of *obj2*. For 2-d arrays this is a
     matrix-product. Neither array is conjugated.
 
-.. cfunction:: PyObject* PyArray_MatrixProduct2(PyObject* obj1, PyObject* obj, PyObject *out)
+.. cfunction:: PyObject* PyArray_MatrixProduct2(PyObject* obj1, PyObject* obj, PyObject* out)
 
     .. versionadded:: 1.6
 
@@ -1821,6 +1898,21 @@ Array Functions
     output array must have the correct shape, type, and be
     C-contiguous, or an exception is raised.
 
+.. cfunction:: PyObject* PyArray_EinsteinSum(char* subscripts, npy_intp nop, PyArrayObject** op_in, PyArray_Descr* dtype, NPY_ORDER order, NPY_CASTING casting, PyArrayObject* out)
+
+   .. versionadded:: 1.6
+
+    Applies the einstein summation convention to the array operands
+    provided, returning a new array or placing the result in *out*.
+    The string in *subscripts* is a comma separated list of index
+    letters. The number of operands is in *nop*, and *op_in* is an
+    array containing those operands. The data type of the output can
+    be forced with *dtype*, the output order can be forced with *order*
+    (:cdata:`NPY_KEEPORDER` is recommended), and when *dtype* is specified,
+    *casting* indicates how permissive the data conversion should be.
+
+    See the :func:`einsum` function for more details.
+
 .. cfunction:: PyObject* PyArray_CopyAndTranspose(PyObject \* op)
 
     A specialized copy and transpose function that works only for 2-d
@@ -1901,6 +1993,9 @@ Other functions
 Array Iterators
 ---------------
 
+As of Numpy 1.6, these array iterators are deprecated in favor of
+the new array iterator, :ctype:`NpyIter`.
+
 An array iterator is a simple way to access the elements of an
 N-dimensional array quickly and efficiently. Section `2
 <#sec-array-iterator>`__ provides more description and examples of
@@ -2415,15 +2510,16 @@ to.
 
 .. cfunction:: int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)
 
-   Convert the Python strings 'C', 'F', 'A', and 'K' into the NPY_ORDER
-   enumeration NPY_CORDER, NPY_FORTRANORDER, NPY_ANYORDER, and NPY_KEEPORDER.
+   Convert the Python strings 'C', 'F', 'A', and 'K' into the :ctype:`NPY_ORDER`
+   enumeration :cdata:`NPY_CORDER`, :cdata:`NPY_FORTRANORDER`,
+   :cdata:`NPY_ANYORDER`, and :cdata:`NPY_KEEPORDER`.
 
 .. cfunction:: int PyArray_CastingConverter(PyObject* obj, NPY_CASTING* casting)
 
    Convert the Python strings 'no', 'equiv', 'safe', 'same_kind', and
-   'unsafe' into the NPY_CASTING enumeration NPY_NO_CASTING,
-   NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and
-   NPY_UNSAFE_CASTING.
+   'unsafe' into the NPY_CASTING enumeration :cdata:`NPY_NO_CASTING`,
+   :cdata:`NPY_EQUIV_CASTING`, :cdata:`NPY_SAFE_CASTING`,
+   :cdata:`NPY_SAME_KIND_CASTING`, and :cdata:`NPY_UNSAFE_CASTING`.
 
 Other conversions
 ^^^^^^^^^^^^^^^^^
@@ -2887,7 +2983,6 @@ Enumerated Types
         **INTNEG_SCALAR**, **FLOAT_SCALAR**, **COMPLEX_SCALAR**,
         **OBJECT_SCALAR**
 
-
     .. cvar:: NPY_NSCALARKINDS
 
        Defined to be the number of scalar kinds
@@ -2895,11 +2990,27 @@ Enumerated Types
 
 .. ctype:: NPY_ORDER
 
-    A variable type indicating the order that an array should be
-    interpreted in. The value of a variable of this type can be
-    :cdata:`NPY_{ORDER}` where ``{ORDER}`` is
+    An enumeration type indicating the element order that an array should be
+    interpreted in. When a brand new array is created, generally
+    only **NPY_CORDER** and **NPY_FORTRANORDER** are used, whereas
+    when one or more inputs are provided, the order can be based on them.
+
+    .. cvar:: NPY_ANYORDER
+
+        Fortran order if all the inputs are Fortran, C otherwise.
+
+    .. cvar:: NPY_CORDER
 
-        **ANYORDER**, **CORDER**, **FORTRANORDER**
+        C order.
+
+    .. cvar:: NPY_FORTRANORDER
+
+        Fortran order.
+
+    .. cvar:: NPY_KEEPORDER
+
+        An order as close to the order of the inputs as possible, even
+        if the input is in neither C nor Fortran order.
 
 .. ctype:: NPY_CLIPMODE
 
@@ -2909,5 +3020,35 @@ Enumerated Types
 
         **CLIP**, **WRAP**, **RAISE**
 
+.. ctype:: NPY_CASTING
+
+    .. versionadded:: 1.6
+
+    An enumeration type indicating how permissive data conversions should
+    be. This is used by the iterator added in NumPy 1.6, and is intended
+    to be used more broadly in a future version.
+
+    .. cvar:: NPY_NO_CASTING
+
+        Only allow identical types.
+
+    .. cvar:: NPY_EQUIV_CASTING
+
+       Allow identical and casts involving byte swapping.
+
+    .. cvar:: NPY_SAFE_CASTING
+
+       Only allow casts which will not cause values to be rounded,
+       truncated, or otherwise changed.
+
+    .. cvar:: NPY_SAME_KIND_CASTING
+
+       Allow any safe casts, and casts between types of the same kind.
+       For example, float64 -> float32 is permitted with this rule.
+
+    .. cvar:: NPY_UNSAFE_CASTING
+
+       Allow any cast, no matter what kind of data loss may occur.
+
 .. index::
    pair: ndarray; C-API