ENH: core: Allow user to pass in output array for dot()

This avoids the memory allocation. It is strict in checking that the
types are correct, but since it is intended as an optimisation, it
should only be used when the user knows what they are doing.

The out parameter is added both to the BLAS and non-BLAS versions of dot().
Tests are included.

1 files changed, 9 insertions, 1 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 2124cbcdf..156da5526 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -864,7 +864,7 @@ Converting data types
 
     Deprecated, PyArray_CanCastTypeTo subsumes its functionality in
     NumPy 1.6 and later.
-    
+
     Equivalent to PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).
 
 .. cfunction:: int PyArray_CanCastTypeTo(PyArray_Descr* fromtype, PyArray_Descr* totype, NPY_CASTING casting)
@@ -1813,6 +1813,14 @@ 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)
+
+    .. versionadded:: 1.6
+
+    Same as PyArray_MatrixProduct, but store the result in *out*.  The
+    output array must have the correct shape, type, and be
+    C-contiguous, or an exception is raised.
+
 .. cfunction:: PyObject* PyArray_CopyAndTranspose(PyObject \* op)
 
     A specialized copy and transpose function that works only for 2-d